ci: Clarify and automate release process (#26181)

.github/scripts/github-helpers.mjs

@@ -9,6 +9,22 @@ export const RELEASE_TRACKS = /** @type { const } */ ([
 	'v1',
 ]);
 
+/**
+ * @typedef {typeof RELEASE_TRACKS[number]} ReleaseTrack
+ * */
+
+/**
+ * @typedef {`${number}.${number}.${number}`} SemVer
+ * */
+
+/**
+ * @typedef {`${RELEASE_PREFIX}${SemVer}`} ReleaseVersion
+ * */
+
+/**
+ * @typedef {{ tag: ReleaseVersion, version: SemVer}} TagVersionInfo
+ * */
+
 export const RELEASE_PREFIX = 'n8n@';
 
 /**
@@ -16,6 +32,8 @@ export const RELEASE_PREFIX = 'n8n@';
  * Returns the *tag string* (e.g. "n8n@2.7.0") or null.
  *
  * @param {string[]} tags
+ *
+ * @returns { ReleaseVersion | null }
  * */
 export function pickHighestReleaseTag(tags) {
 	const versions = tags
@@ -24,13 +42,13 @@ export function pickHighestReleaseTag(tags) {
 		.filter(({ v }) => semver.valid(v))
 		.sort((a, b) => semver.rcompare(a.v, b.v));
 
-	return versions[0]?.tag ?? null;
+	return /** @type { ReleaseVersion } */ (versions[0]?.tag) ?? null;
 }
 
 /**
- * @param {string} track
+ * @param {any} track
  *
- * @returns { typeof RELEASE_TRACKS[number] }
+ * @returns { ReleaseTrack }
  * */
 export function ensureReleaseTrack(track) {
 	if (!RELEASE_TRACKS.includes(track)) {
@@ -40,6 +58,30 @@ export function ensureReleaseTrack(track) {
 	return track;
 }
 
+/**
+ * Resolve a release track tag (stable/beta/etc.) to the corresponding
+ * n8n@x.y.z tag pointing at the same commit.
+ *
+ * Returns null if the track tag or release tag is missing.
+ *
+ * @param { typeof RELEASE_TRACKS[number] } track
+ *
+ * @returns { TagVersionInfo }
+ * */
+export function resolveReleaseTagForTrack(track) {
+	const commit = getCommitForRef(track);
+	if (!commit) return null;
+
+	const tagsAtCommit = listTagsPointingAt(commit);
+	const releaseTag = pickHighestReleaseTag(tagsAtCommit);
+	if (!releaseTag) return null;
+
+	return {
+		tag: releaseTag,
+		version: stripReleasePrefixes(releaseTag),
+	};
+}
+
 /**
  * Resolve a release track tag (stable/beta/etc.) to the corresponding
  * release-candidate/<major>.<minor>.x branch, based on the n8n@<x.y.z> tag
@@ -66,9 +108,13 @@ export function resolveRcBranchForTrack(track) {
 
 /**
  * @param {string} tag
+ *
+ * @returns { SemVer }
  * */
 export function stripReleasePrefixes(tag) {
-	return tag.startsWith(RELEASE_PREFIX) ? tag.slice(RELEASE_PREFIX.length) : tag;
+	return /** @type { SemVer } */ (
+		tag.startsWith(RELEASE_PREFIX) ? tag.slice(RELEASE_PREFIX.length) : tag
+	);
 }
 
 /**