@astra-kit/rp 0.0.0-stage → 0.10.0

package/src/create-version/state.js

@@ -0,0 +1,461 @@
+/**
+ * Gathers the snapshot consumed by `plan.js`: current branch, uncommitted
+ * changes, `main` compared with `origin/main`, the version and subject of
+ * `HEAD`, the commit of a detached release tag on `origin`, the last release,
+ * the commits waiting to be released, the pull request of a feature branch,
+ * the published versions, the npm credentials (when the plan would publish to
+ * npm) and pending migrations.
+ *
+ * Every reader is read-only; the only network operations are `git fetch`,
+ * `git ls-remote`, `gh pr view`, `npm view`, `npm whoami`, `npm owner ls` and
+ * whatever the project migrations adapter reads.
+ *
+ * @module create-version/state
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+import { readUnreleased } from "../changelog.js";
+import { CHANGELOG_FILE } from "../constants/changelog.js";
+import {
+  MAIN_BRANCH,
+  MIGRATION_STATUS,
+  NPM_AUTH_STATUS,
+  NPM_NOT_FOUND_CODE,
+  NO_PULL_REQUEST_MESSAGE_PATTERN,
+  PULL_REQUEST_JSON_FIELDS,
+  RELEASE_REMOTE,
+  REMOTE_MAIN_REF,
+} from "../constants/create-version.js";
+import { toReleaseTag } from "../versions.js";
+import { readChangelogUpdateState } from "./changelog.js";
+import { describeError } from "./errors.js";
+import { readJsonManifest } from "./json.js";
+import { checkRegistryAccess, lookupRegistryVersions } from "./registry.js";
+import { checkNpmPublishAccess, failedLookup, lookupPublishedVersions, resolvePublishRegistry } from "./npm.js";
+import { createGitReader, findVersionChangeCommit, listCommits, readPackageVersionAt, runCaptured } from "./process.js";
+
+/**
+ * @typedef {import("./process.js").GitReader} GitReader
+ * @typedef {import("./plan.js").ReleaseState} ReleaseState
+ * @typedef {import("./plan.js").PullRequestSnapshot} PullRequestSnapshot
+ * @typedef {import("./config.js").MigrationCheck} MigrationCheck
+ * @typedef {import("./plan.js").LastReleaseSnapshot} LastReleaseSnapshot
+ * @typedef {ReleaseState & { packageName: string, releasedVersion: string | null, lastRelease: LastReleaseSnapshot | null }} ReleaseSnapshot
+ */
+
+/**
+ * Returns the release tag of a version when it points exactly at a commit.
+ *
+ * @param {GitReader} reader - Git reader.
+ * @param {string | null} version - Version whose `vX.Y.Z` tag is looked up.
+ * @param {string} sha - Commit the tag must point at.
+ * @returns {Promise<string | null>} Tag name, or `null` when it is missing or points elsewhere.
+ */
+async function findReleaseTagAt(reader, version, sha) {
+  if (!version) {
+    return null;
+  }
+
+  const tag = toReleaseTag(version);
+  const taggedSha = await reader.tryGit(["rev-parse", "--verify", "--quiet", `refs/tags/${tag}^{commit}`]);
+  return taggedSha === sha ? tag : null;
+}
+
+/**
+ * Reads the commit a release tag points at on `origin`, so a detached publication can prove that
+ * its commit and tag already reached the remote. An annotated tag is resolved through its peeled
+ * `^{}` entry; a lightweight tag points at the commit directly.
+ *
+ * @param {GitReader} reader - Git reader.
+ * @param {string} tag - Release tag such as `v1.2.0`.
+ * @returns {Promise<string | null>} Commit of the tag on `origin`, or `null` when it is missing or
+ *   `origin` cannot be read.
+ */
+async function readRemoteReleaseTagCommit(reader, tag) {
+  const tagRef = `refs/tags/${tag}`;
+  const peeledRef = `${tagRef}^{}`;
+  const output = await reader.tryGit(["ls-remote", RELEASE_REMOTE, tagRef, peeledRef]);
+  const shaByRef = new Map(
+    (output ?? "")
+      .split("\n")
+      .map((line) => line.trim().split(/\s+/u))
+      .filter((fields) => fields.length === 2)
+      .map(([sha, ref]) => [ref, sha])
+  );
+  return shaByRef.get(peeledRef) ?? shaByRef.get(tagRef) ?? null;
+}
+
+/**
+ * Finds the last release on a revision: the newest commit that changed the
+ * top-level `version` of `package.json`. It covers `X.Y.Z` release commits,
+ * other release subjects and projects that bumped versions by hand.
+ *
+ * @param {GitReader} reader - Git reader.
+ * @param {string} revision - Revision such as `origin/main`.
+ * @returns {Promise<LastReleaseSnapshot | null>} Last release with its subject and whether its
+ *   `vX.Y.Z` tag points at it, or `null` without history.
+ */
+export async function findLastRelease(reader, revision) {
+  const sha = await findVersionChangeCommit(reader, revision);
+
+  if (!sha) {
+    return null;
+  }
+
+  const version = await readPackageVersionAt(reader, sha);
+  const subject = await reader.tryGit(["log", "-1", "--format=%s", sha]);
+  return { sha, version, subject, tagged: (await findReleaseTagAt(reader, version, sha)) !== null };
+}
+
+/**
+ * Looks up the pull request of a branch with the GitHub CLI.
+ *
+ * @param {string} repositoryRoot - Repository root.
+ * @param {string} branchName - Head branch.
+ * @returns {Promise<{ pullRequest: PullRequestSnapshot | null, githubError: string | null }>} Pull request or error.
+ */
+export async function lookupPullRequest(repositoryRoot, branchName) {
+  const result = await runCaptured("gh", ["pr", "view", branchName, "--json", PULL_REQUEST_JSON_FIELDS], { cwd: repositoryRoot });
+
+  if (result.status === 0) {
+    try {
+      return { pullRequest: JSON.parse(result.stdout), githubError: null };
+    } catch (error) {
+      return { pullRequest: null, githubError: `respuesta inválida de gh (${describeError(error)})` };
+    }
+  }
+
+  if (NO_PULL_REQUEST_MESSAGE_PATTERN.test(result.stderr)) {
+    return { pullRequest: null, githubError: null };
+  }
+
+  return { pullRequest: null, githubError: result.stderr.split("\n")[0] || "gh no respondió" };
+}
+
+/**
+ * Reads the feature branch snapshot (upstream, unpushed and unmerged commits).
+ *
+ * @param {GitReader} reader - Git reader.
+ * @param {string} branchName - Current branch.
+ * @returns {Promise<import("./plan.js").FeatureBranchSnapshot>} Snapshot.
+ */
+async function readFeatureBranch(reader, branchName) {
+  const headSha = await reader.git(["rev-parse", "HEAD"]);
+  const aheadOfMainCount = Number((await reader.tryGit(["rev-list", "--count", `${REMOTE_MAIN_REF}..HEAD`])) ?? 0);
+  const upstreamUnpushed = await reader.tryGit(["rev-list", "--count", "@{upstream}..HEAD"]);
+
+  return {
+    name: branchName,
+    headSha,
+    hasUpstream: upstreamUnpushed !== null,
+    unpushedCount: upstreamUnpushed === null ? aheadOfMainCount : Number(upstreamUnpushed),
+    aheadOfMainCount,
+  };
+}
+
+/**
+ * Reads the `[Unreleased]` block of the working-tree CHANGELOG.md.
+ *
+ * @param {string} repositoryRoot - Repository root.
+ * @returns {{ exists: boolean, entryCount: number, unknownSections: string[] }} Unreleased state.
+ */
+export function readChangelogState(repositoryRoot) {
+  const changelogPath = path.join(repositoryRoot, CHANGELOG_FILE);
+
+  if (!existsSync(changelogPath)) {
+    return { exists: false, entryCount: 0, unknownSections: [] };
+  }
+
+  const { exists, entryCount, unknownSections } = readUnreleased(readFileSync(changelogPath, "utf8"));
+  return { exists, entryCount, unknownSections };
+}
+
+/**
+ * Runs the project migrations check, turning any failure into an `unknown` result.
+ *
+ * @param {(() => Promise<MigrationCheck> | MigrationCheck) | null} checkMigrations - Adapter bound to its hook context.
+ * @returns {Promise<MigrationCheck | null>} Migration state, or `null` for projects without migrations.
+ */
+export async function readMigrations(checkMigrations) {
+  if (!checkMigrations) {
+    return null;
+  }
+
+  try {
+    return await checkMigrations();
+  } catch (error) {
+    return { status: MIGRATION_STATUS.unknown, pending: [], target: null, reason: describeError(error) };
+  }
+}
+
+/**
+ * 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.
+ */
+export async function lookupNpmOnPublishRegistry(lookupNpm, manifest, repositoryRoot) {
+  const registry = await resolveRegistrySafely(manifest, repositoryRoot);
+
+  return registry.registryUrl === null
+    ? failedLookup(registry.reason)
+    : lookupNpm(String(manifest.name), repositoryRoot, registry.registryUrl);
+}
+
+/**
+ * Lists the published versions of a package for the diagnosis: on the selected registry, or on the
+ * registry the working-tree manifest publishes to when no registry is selected; shared with the monorepo mode.
+ *
+ * @param {import("./registry.js").RegistrySelection | undefined} registrySelection - Selected registry, if any.
+ * @param {Record<string, unknown>} manifest - Working-tree manifest of the package.
+ * @param {string} repositoryRoot - Repository root, where routing and credentials are read.
+ * @param {string} packageRoot - Package directory.
+ * @param {typeof lookupPublishedVersions} lookupNpm - npm lookup adapter.
+ * @returns {Promise<import("./npm.js").NpmLookup>} Published versions, or a failed lookup.
+ */
+export function lookupPackageVersions(registrySelection, manifest, repositoryRoot, packageRoot, lookupNpm) {
+  return registrySelection ? lookupRegistryVersions(registrySelection, manifest, repositoryRoot, packageRoot, lookupNpm) : lookupNpmOnPublishRegistry(lookupNpm, manifest, repositoryRoot);
+}
+
+/**
+ * Checks the credentials that would publish a package and confirms a first publication against its
+ * published versions (see {@link confirmFirstPublication}); shared with the monorepo mode.
+ *
+ * @param {import("./registry.js").RegistrySelection | undefined} registrySelection - Selected registry, if any.
+ * @param {Record<string, unknown>} manifest - Working-tree manifest of the package.
+ * @param {string} repositoryRoot - Repository root, where routing and credentials are read.
+ * @param {string} packageRoot - Package directory.
+ * @param {typeof checkNpmPublishAccess} checkNpmAccess - npm credential check adapter.
+ * @param {import("./npm.js").NpmLookup | null} npm - Published versions, or `null` when npm is not tracked.
+ * @returns {Promise<import("./npm.js").NpmAuthCheck>} Credential check.
+ */
+export async function checkPackageAccess(registrySelection, manifest, repositoryRoot, packageRoot, checkNpmAccess, npm) {
+  const npmAuth = registrySelection ? await checkRegistryAccess(registrySelection, manifest, repositoryRoot, packageRoot, checkNpmAccess) : await checkNpmAuthOnPublishRegistry(checkNpmAccess, manifest, repositoryRoot);
+  return confirmFirstPublication(npmAuth, npm);
+}
+
+/**
+ * Reads the changelog of a package for the diagnosis: its `[Unreleased]` block and whether it was
+ * updated since the last release; shared with the monorepo mode.
+ *
+ * @param {GitReader} reader - Git reader.
+ * @param {string} repositoryRoot - Repository root.
+ * @param {string} packageRoot - Package directory holding the changelog.
+ * @param {string} changelogPath - Changelog path relative to the root.
+ * @param {string | null} lastReleaseSha - Commit of the last release, or `null` without one.
+ * @returns {Promise<ReleaseSnapshot["changelog"]>} Changelog state.
+ */
+export async function readPackageChangelogState(reader, repositoryRoot, packageRoot, changelogPath, lastReleaseSha) {
+  return {
+    ...readChangelogState(packageRoot),
+    ...(await readChangelogUpdateState(reader, repositoryRoot, changelogPath, lastReleaseSha)),
+  };
+}
+
+/**
+ * Resolves the publish registry without throwing.
+ *
+ * @param {Record<string, unknown>} manifest - Working-tree `package.json`.
+ * @param {string} repositoryRoot - Repository root.
+ * @returns {Promise<{ registryUrl: string | null, reason: string | null }>} Registry, or why it cannot be resolved.
+ */
+async function resolveRegistrySafely(manifest, repositoryRoot) {
+  try {
+    return { registryUrl: await resolvePublishRegistry(manifest, repositoryRoot), reason: null };
+  } catch (error) {
+    return { registryUrl: null, reason: describeError(error) };
+  }
+}
+
+/**
+ * Checks the npm credentials on the registry the working-tree manifest publishes to.
+ *
+ * @param {typeof checkNpmPublishAccess} checkAccess - npm credential check adapter.
+ * @param {Record<string, unknown>} manifest - Working-tree `package.json`.
+ * @param {string} repositoryRoot - Repository root.
+ * @returns {Promise<import("./npm.js").NpmAuthCheck>} Check result; an `unknown` one when the registry cannot be resolved.
+ */
+export async function checkNpmAuthOnPublishRegistry(checkAccess, manifest, repositoryRoot) {
+  const registry = await resolveRegistrySafely(manifest, repositoryRoot);
+
+  return registry.registryUrl === null
+    ? { status: NPM_AUTH_STATUS.unknown, user: null, source: null, registryUrl: "", packageName: String(manifest.name), owners: [], firstPublication: false, reason: registry.reason }
+    : checkAccess(String(manifest.name), repositoryRoot, registry.registryUrl);
+}
+
+/**
+ * Confirms a first publication (`npm owner ls` answered E404) against the versions `npm view`
+ * listed with the same token. Registries hide a private package from users without access, so an
+ * owner E404 only means "new package" when `npm view` does not list versions either: when it does,
+ * the package exists and the token cannot manage it, which blocks like a user that is not an owner.
+ *
+ * @param {import("./npm.js").NpmAuthCheck} npmAuth - Credential check.
+ * @param {import("./npm.js").NpmLookup | null} npm - Published versions, or `null` when npm is not tracked.
+ * @returns {import("./npm.js").NpmAuthCheck} The same check, or a `notOwner` one when the package already has versions.
+ */
+export function confirmFirstPublication(npmAuth, npm) {
+  const publishedCount = npm?.publishedVersions.length ?? 0;
+
+  if (!npmAuth.firstPublication || publishedCount === 0) {
+    return npmAuth;
+  }
+
+  return {
+    ...npmAuth,
+    status: NPM_AUTH_STATUS.notOwner,
+    firstPublication: false,
+    reason: `npm view lista versiones publicadas de ${npmAuth.packageName} (${publishedCount}), pero npm owner ls respondió ${NPM_NOT_FOUND_CODE}: el token no tiene acceso al paquete.`,
+  };
+}
+
+/**
+ * @typedef {{
+ *   currentBranch: string | null,
+ *   workingTreeChanges: string[],
+ *   branch: import("./plan.js").FeatureBranchSnapshot | null,
+ *   pullRequest: PullRequestSnapshot | null,
+ *   githubError: string | null,
+ *   main: { aheadCommits: import("./process.js").CommitRecord[], behindCount: number },
+ *   remoteMainExists: boolean,
+ * }} RepositorySnapshot
+ *   What every release mode reads from Git before looking at packages: the branch and its pull
+ *   request, the working tree and `main` compared with `origin/main`.
+ */
+
+/**
+ * Fetches `origin` and reads the repository part of the snapshot, shared by the single-package and
+ * the monorepo modes.
+ *
+ * @param {{
+ *   repositoryRoot: string,
+ *   reader: GitReader,
+ *   onProgress: (label: string) => void,
+ *   lookupPullRequestFor: typeof lookupPullRequest,
+ * }} options - Repository, reader, progress callback and pull request adapter.
+ * @returns {Promise<RepositorySnapshot>} Repository snapshot.
+ */
+export async function readRepositorySnapshot({ repositoryRoot, reader, onProgress, lookupPullRequestFor }) {
+  onProgress("Sincronizando con origin (fetch)");
+  await reader.git(["fetch", RELEASE_REMOTE, "--prune", "--tags", "--quiet"]);
+
+  onProgress("Leyendo el estado de Git");
+  const currentBranch = await reader.tryGit(["symbolic-ref", "--quiet", "--short", "HEAD"]);
+  // Every untracked file, not only its directory, so the plan sees the extension of each one; with
+  // core.quotePath off, non-ASCII paths come verbatim instead of octal-escaped.
+  const statusOutput = await reader.git(["-c", "core.quotePath=false", "status", "--porcelain", "--untracked-files=all"]);
+  const workingTreeChanges = statusOutput.split("\n").map((line) => line.trimEnd()).filter(Boolean);
+  const localMainExists = (await reader.tryGit(["rev-parse", "--verify", "--quiet", MAIN_BRANCH])) !== null;
+  const remoteMainExists = (await reader.tryGit(["rev-parse", "--verify", "--quiet", REMOTE_MAIN_REF])) !== null;
+  const aheadCommits = localMainExists && remoteMainExists ? await listCommits(reader, `${REMOTE_MAIN_REF}..${MAIN_BRANCH}`) : [];
+  const behindCount =
+    localMainExists && remoteMainExists ? Number((await reader.tryGit(["rev-list", "--count", `${MAIN_BRANCH}..${REMOTE_MAIN_REF}`])) ?? 0) : 0;
+
+  let branch = null;
+  let pullRequest = null;
+  let githubError = null;
+
+  if (currentBranch && currentBranch !== MAIN_BRANCH) {
+    onProgress(`Revisando la rama ${currentBranch} y su PR`);
+    branch = await readFeatureBranch(reader, currentBranch);
+    ({ pullRequest, githubError } = await lookupPullRequestFor(repositoryRoot, currentBranch));
+  }
+
+  return { currentBranch, workingTreeChanges, branch, pullRequest, githubError, main: { aheadCommits, behindCount }, remoteMainExists };
+}
+
+/**
+ * Gathers the complete release snapshot.
+ *
+ * @param {{
+ *   repositoryRoot: string,
+ *   trackNpm?: boolean,
+ *   checkMigrations?: (() => Promise<MigrationCheck> | MigrationCheck) | null,
+ *   onProgress?: (label: string) => void,
+ *   lookupNpm?: typeof lookupPublishedVersions,
+ *   checkNpmAuth?: ((snapshot: ReleaseSnapshot) => boolean) | null,
+ *   checkNpmAccess?: typeof checkNpmPublishAccess,
+ *   lookupPullRequestFor?: typeof lookupPullRequest,
+ *   registrySelection?: import("./registry.js").RegistrySelection,
+ * }} options - Repository, adapters and progress callback. `checkNpmAuth` receives the snapshot
+ *   without credentials and decides whether the npm credentials are checked (when the plan would publish to npm).
+ * @returns {Promise<ReleaseSnapshot>} Snapshot accepted by `buildReleasePlan`.
+ */
+export async function collectReleaseState({
+  repositoryRoot,
+  trackNpm = false,
+  checkMigrations = null,
+  onProgress = () => {},
+  lookupNpm = lookupPublishedVersions,
+  checkNpmAuth = null,
+  checkNpmAccess = checkNpmPublishAccess,
+  lookupPullRequestFor = lookupPullRequest,
+  registrySelection,
+}) {
+  const reader = createGitReader(repositoryRoot);
+  const repository = await readRepositorySnapshot({ repositoryRoot, reader, onProgress, lookupPullRequestFor });
+  const { currentBranch, workingTreeChanges, branch, pullRequest, githubError, main, remoteMainExists } = repository;
+  const headVersion = await readPackageVersionAt(reader, "HEAD");
+  const headSubject = await reader.tryGit(["log", "-1", "--format=%s", "HEAD"]);
+  const headSha = await reader.tryGit(["rev-parse", "HEAD"]);
+  const headReleaseTag = headSha ? await findReleaseTagAt(reader, headVersion, headSha) : null;
+  // Only a detached publication from a tag needs to prove that the tag is on origin.
+  const remoteReleaseTagSha = !currentBranch && headReleaseTag ? await readRemoteReleaseTagCommit(reader, headReleaseTag) : null;
+  // A tag missing from origin can still be pushed from the detached HEAD when origin/main already has its commit.
+  const headOnRemoteMain =
+    !currentBranch && headReleaseTag && !remoteReleaseTagSha && remoteMainExists
+      ? (await reader.tryGit(["merge-base", "--is-ancestor", "HEAD", REMOTE_MAIN_REF])) !== null
+      : false;
+  const releasedVersion = remoteMainExists ? await readPackageVersionAt(reader, REMOTE_MAIN_REF) : null;
+  const lastRelease = remoteMainExists ? await findLastRelease(reader, REMOTE_MAIN_REF) : null;
+  const unreleasedCommits = remoteMainExists ? await listCommits(reader, lastRelease ? `${lastRelease.sha}..${REMOTE_MAIN_REF}` : REMOTE_MAIN_REF) : [];
+
+  const manifest = readJsonManifest(repositoryRoot);
+  let npm = null;
+
+  if (trackNpm) {
+    onProgress("Consultando npm");
+    npm = await lookupPackageVersions(registrySelection, manifest, repositoryRoot, repositoryRoot, lookupNpm);
+  }
+
+  if (checkMigrations) {
+    onProgress("Consultando migraciones pendientes");
+  }
+  const migrations = await readMigrations(checkMigrations);
+
+  /** @type {ReleaseSnapshot} */
+  const snapshot = {
+    packageName: manifest.name,
+    currentBranch,
+    workingTreeChanges,
+    branch,
+    pullRequest,
+    githubError,
+    main,
+    headVersion,
+    headSubject,
+    headSha,
+    headReleaseTag,
+    remoteReleaseTagSha,
+    headOnRemoteMain,
+    releasedVersion,
+    lastRelease,
+    unreleasedCommits,
+    npm,
+    npmAuth: null,
+    migrations,
+    changelog: await readPackageChangelogState(reader, repositoryRoot, repositoryRoot, CHANGELOG_FILE, lastRelease?.sha ?? null),
+  };
+
+  if (checkNpmAuth?.(snapshot)) {
+    onProgress("Verificando las credenciales de npm");
+    snapshot.npmAuth = await checkPackageAccess(registrySelection, manifest, repositoryRoot, repositoryRoot, checkNpmAccess, npm);
+  }
+
+  return snapshot;
+}

package/src/create-version/strict-utf8.js

@@ -0,0 +1,11 @@
+/**
+ * Strict UTF-8 decoding for files the release rewrites as text.
+ *
+ * @module create-version/strict-utf8
+ */
+
+/**
+ * Strict UTF-8 decoder: invalid bytes (such as an ISO-8859-1 file) throw instead of turning into
+ * U+FFFD, and a byte order mark is kept as text, so writing the text back never changes other bytes.
+ */
+export const STRICT_UTF8_DECODER = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });

package/src/create-version/templates/release.yml

@@ -0,0 +1,52 @@
+name: Release
+run-name: "astra-rp release ${{ inputs.tag }} ${{ inputs.sha }}"
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Versión creada desde local"
+        required: true
+        type: string
+      tag:
+        description: "Tag exacto del release"
+        required: true
+        type: string
+      sha:
+        description: "Commit exacto del tag"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+__RELEASE_PERMISSIONS__
+
+concurrency:
+  group: "astra-rp-release"
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    env:
+      HUSKY: '0'
+__RELEASE_ENVIRONMENT__
+    steps:
+      - name: Checkout del release
+        uses: actions/checkout@v4
+        with:
+          ref: refs/tags/${{ inputs.tag }}
+          fetch-depth: 0
+          persist-credentials: true
+__RELEASE_IDENTITY_CHECK__
+__NODE_SETUP__
+__DENO_SETUP__
+__PACKAGE_SETUP__
+__DEPLOYMENT_SETUP__
+      - name: Checks y publicación del release
+        env:
+          ASTRA_RP_RELEASE_VERSION: ${{ inputs.version }}
+          ASTRA_RP_RELEASE_SHA: ${{ inputs.sha }}
+          RELEASE_TAG: ${{ inputs.tag }}
+        run: __RELEASE_COMMAND__
+__DEPLOYMENT_STEP__

package/src/create-version/templates/vercel-ignore-build.mjs

@@ -0,0 +1,66 @@
+/**
+ * Gates Git deployments while an exact release is owned by CI.
+ *
+ * A commit cannot contain its own SHA, so the release commit is identified as the one that
+ * changes `.astra-rp/release.json` against its first parent; later commits keep the metadata
+ * untouched and fall through to the original gate. Without a readable parent (shallow clone or
+ * first commit) the release commit is recognized by its own `Astra-Rp-Execution: ci` trailer,
+ * which later commits never carry, so the gate stays closed until the release workflow deploys.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+
+const RELEASE_METADATA_FILE = '.astra-rp/release.json';
+/** Revision compared against the deployed commit; absent in shallow clones and on the first commit. */
+const PARENT_REVISION = 'HEAD^';
+/** `git diff --quiet` status reporting that the path changed between both commits. */
+const GIT_DIFF_CHANGED_STATUS = 1;
+/** Trailer that `astra-rp create-version` writes in the release commit (mirrors `RELEASE_EXECUTION_TRAILER`). */
+const RELEASE_EXECUTION_TRAILER = 'Astra-Rp-Execution';
+/** Trailer value of a release whose deployment is delegated to CI. */
+const CI_RELEASE_EXECUTION = 'ci';
+
+/**
+ * Runs a read-only Git command in the deployed checkout.
+ * @param {string[]} gitArguments - Git arguments.
+ * @returns {import("node:child_process").SpawnSyncReturns<string>} Git result.
+ */
+function runGit(gitArguments) {
+  return spawnSync('git', gitArguments, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true });
+}
+
+/** @returns {boolean} Whether the deployed commit carries exactly one `Astra-Rp-Execution: ci` trailer value. */
+function hasCiReleaseTrailer() {
+  const trailers = runGit(['log', '-1', `--format=%(trailers:key=${RELEASE_EXECUTION_TRAILER},valueonly=true)`, 'HEAD']);
+  if (trailers.status !== 0) return false;
+  const recordedValues = [...new Set(trailers.stdout.split('\n').map((value) => value.trim()).filter(Boolean))];
+  return recordedValues.length === 1 && recordedValues[0] === CI_RELEASE_EXECUTION;
+}
+
+/** @returns {boolean} Whether the deployed commit is the one that wrote the release metadata. */
+function isReleaseMetadataCommit() {
+  const parent = runGit(['rev-parse', '--verify', '--quiet', `${PARENT_REVISION}^{commit}`]);
+  if (parent.status !== 0) return hasCiReleaseTrailer();
+  const changed = runGit(['diff', '--quiet', PARENT_REVISION, 'HEAD', '--', RELEASE_METADATA_FILE]);
+  return changed.status === GIT_DIFF_CHANGED_STATUS;
+}
+
+let delegated = false;
+try {
+  if (existsSync(RELEASE_METADATA_FILE)) {
+    const metadata = JSON.parse(readFileSync(RELEASE_METADATA_FILE, 'utf8'));
+    const manifest = JSON.parse(readFileSync('package.json', 'utf8'));
+    delegated = metadata.execution === 'ci' && metadata.version === manifest.version && isReleaseMetadataCommit();
+  }
+} catch {
+  console.error('No se pudo leer la metadata del release; se omite el despliegue automático.');
+  process.exit(0);
+}
+if (delegated) {
+  console.log('El release está en CI; producción espera a que pasen los checks.');
+  process.exit(0);
+}
+const originalIgnoreCommand = __ORIGINAL_IGNORE_COMMAND__;
+process.exitCode = originalIgnoreCommand
+  ? spawnSync(originalIgnoreCommand, { shell: true, stdio: 'inherit', windowsHide: true }).status ?? 0
+  : 1;

package/src/guard-publish.js

@@ -0,0 +1,77 @@
+/**
+ * `prepublishOnly` guard of the packages released with astra-rp: they are published with npm by
+ * `create-version` (run through the project's package manager), 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";
+import { describeProjectCommands } from "./package-manager.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 (pnpm, yarn or bun), which is also
+ *   the one the project uses: the message names its own create-version command.
+ * @returns {string} Message in Spanish with what to run instead.
+ */
+export function buildBlockedPublishMessage(packageManager) {
+  const { createVersion } = describeProjectCommands(/** @type {import("./package-manager.js").PackageManagerName} */ (packageManager));
+  return (
+    `astra-rp guard-publish: no publiques con ${packageManager}. Este paquete se publica con \`${createVersion}\`, ` +
+    "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]);
+}