ci: recover alpha train after empty changesets (#277)

## Summary
- prune empty changesets in the release-alpha-train runner checkout
before changesets/action decides between versioning and publishing
- make release-alpha-train ignore prerelease-tracked changesets from
.changeset/pre.json and empty changesets when checking whether
GoReleaser can complete the current train
- extend release-plan and release-helper tests so consumed prerelease
changesets plus empty CI changesets do not block recovery, while real
unconsumed package changesets still do

## Validation
- corepack pnpm nx test @zitadel/cli --
tests/unit/scripts/release-alpha-train.test.ts
tests/unit/scripts/check-alpha-release-plan.test.ts
- corepack pnpm run check -- --only release
- node scripts/release-alpha-train.mjs status --published false --remote
false
- git diff --check

## Release notes / changeset
- Added an empty changeset: .changeset/fix-alpha-prerelease-recovery.md

## Notes
- Run 27445059622 skipped GoReleaser because changesets/action returned
before npm publish on empty changesets, then the alpha status guard
treated prerelease bookkeeping files as pending changesets. After this
patch, the local status probe for the same 0.1.0-alpha.3 state reports
should_complete=true, create_tag=true, and run_goreleaser=true.

Author: fforootd

.changeset/fix-alpha-prerelease-recovery.md

@@ -0,0 +1,3 @@
+---
+---
+

.github/workflows/ci.yml

@@ -842,6 +842,9 @@ jobs:
       - name: Build packages
         run: corepack pnpm nx run-many -t build
 
+      - name: Prune empty changesets before publish decision
+        run: node scripts/release-alpha-train.mjs prune-empty-changesets
+
       - name: Create release PR or publish to npm
         id: changesets
         uses: changesets/action@v1

apps/cli/tests/unit/scripts/check-alpha-release-plan.test.ts

@@ -107,6 +107,22 @@ describe("check-alpha-release-plan script", () => {
     ).rejects.toThrow("Changesets must not create package-shaped GitHub Releases");
   });
 
+  it("rejects a workflow that lets empty changesets suppress npm publishing", async () => {
+    const { cwd, statusPath } = await fixtureRepo({
+      ciWorkflow: validCiWorkflow().replace(
+        [
+          "      - name: Prune empty changesets before publish decision",
+          "        run: node scripts/release-alpha-train.mjs prune-empty-changesets",
+        ].join("\n"),
+        "",
+      ),
+    });
+
+    await expect(
+      checkAlphaReleasePlanModule.checkAlphaReleasePlan({ cwd, statusPath }),
+    ).rejects.toThrow("must prune empty changesets before Changesets decides whether to publish");
+  });
+
   it("rejects alpha release notes generated inside the checkout", async () => {
     const { cwd, statusPath } = await fixtureRepo({
       ciWorkflow: validCiWorkflow().replace(
@@ -241,7 +257,11 @@ function validCiWorkflow(): string {
     "      packages: write",
     "      id-token: write",
     "    steps:",
-    "      - uses: changesets/action@v1",
+    "      - name: Prune empty changesets before publish decision",
+    "        run: node scripts/release-alpha-train.mjs prune-empty-changesets",
+    "",
+    "      - name: Create release PR or publish to npm",
+    "        uses: changesets/action@v1",
     "        with:",
     "          createGithubReleases: false",
     "      - id: alpha-status",

apps/cli/tests/unit/scripts/release-alpha-train.test.ts

@@ -7,6 +7,7 @@ import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
 type ReleaseAlphaTrainModule = {
   PUBLIC_PACKAGE_MANIFESTS: string[];
   PUBLIC_PACKAGE_NAMES: string[];
+  pruneEmptyChangesets: (options: { cwd: string }) => Promise<string[]>;
   inspectAlphaReleaseTrain: (options: {
     cwd: string;
     execFile?: ExecFileMock;
@@ -147,6 +148,65 @@ describe("release-alpha-train script", () => {
     });
   });
 
+  it("ignores prerelease-tracked and empty changesets when recovering a versioned train", async () => {
+    const cwd = await fixtureRepo({
+      changesets: {
+        "add-spa-sdks.md": releaseChangeset("@zitadel/cli", "minor"),
+        "ci-only.md": emptyChangeset(),
+      },
+      preChangesets: ["add-spa-sdks"],
+    });
+
+    await expect(
+      releaseAlphaTrain.inspectAlphaReleaseTrain({
+        cwd,
+        execFile: commandMock(),
+        remote: false,
+      }),
+    ).resolves.toMatchObject({
+      shouldComplete: true,
+      skipReason: "",
+    });
+  });
+
+  it("blocks unconsumed release changesets before npm publishes", async () => {
+    const cwd = await fixtureRepo({
+      changesets: {
+        "feature.md": releaseChangeset("@zitadel/cli", "minor"),
+      },
+    });
+
+    await expect(
+      releaseAlphaTrain.inspectAlphaReleaseTrain({
+        cwd,
+        execFile: commandMock(),
+        remote: false,
+      }),
+    ).resolves.toMatchObject({
+      shouldComplete: false,
+      skipReason: "pending changesets: feature.md",
+    });
+  });
+
+  it("prunes empty changesets before Changesets decides whether to publish", async () => {
+    const cwd = await fixtureRepo({
+      changesets: {
+        "ci-only.md": emptyChangeset(),
+        "feature.md": releaseChangeset("@zitadel/cli", "minor"),
+      },
+    });
+
+    await expect(releaseAlphaTrain.pruneEmptyChangesets({ cwd })).resolves.toEqual([
+      "ci-only.md",
+    ]);
+    await expect(readFile(join(cwd, ".changeset/ci-only.md"), "utf8")).rejects.toMatchObject({
+      code: "ENOENT",
+    });
+    await expect(readFile(join(cwd, ".changeset/feature.md"), "utf8")).resolves.toContain(
+      "@zitadel/cli",
+    );
+  });
+
   it("skips GoReleaser when both the GitHub Release and container image already exist", async () => {
     const cwd = await fixtureRepo();
 
@@ -196,8 +256,10 @@ describe("release-alpha-train script", () => {
 
 async function fixtureRepo(
   options: {
+    changesets?: Record<string, string>;
     versions?: Record<string, string>;
     fixedGroupExtra?: string[];
+    preChangesets?: string[];
   } = {},
 ): Promise<string> {
   const cwd = await mkdtemp(join(tmpdir(), "zitadel-alpha-train-"));
@@ -231,10 +293,36 @@ async function fixtureRepo(
       2,
     )}\n`,
   );
+  if (options.preChangesets) {
+    await writeFile(
+      join(cwd, ".changeset/pre.json"),
+      `${JSON.stringify(
+        {
+          mode: "pre",
+          tag: "alpha",
+          initialVersions: {},
+          changesets: options.preChangesets,
+        },
+        null,
+        2,
+      )}\n`,
+    );
+  }
+  for (const [file, content] of Object.entries(options.changesets ?? {})) {
+    await writeFile(join(cwd, ".changeset", file), content);
+  }
 
   return cwd;
 }
 
+function releaseChangeset(name: string, type: "major" | "minor" | "patch"): string {
+  return ["---", `"${name}": ${type}`, "---", "", "Release package change.", ""].join("\n");
+}
+
+function emptyChangeset(): string {
+  return ["---", "---", "", "CI-only change.", ""].join("\n");
+}
+
 function commandMock(
   options: {
     headCommit?: string;

scripts/check-alpha-release-plan.mjs

@@ -177,6 +177,17 @@ export async function validateReleaseTooling(cwd, readFileFn = readFileDefault)
     "createGithubReleases: false",
     "Changesets must not create package-shaped GitHub Releases",
   );
+  assertJobContains(
+    ciWorkflow,
+    "release-alpha-train",
+    [
+      "      - name: Prune empty changesets before publish decision",
+      "        run: node scripts/release-alpha-train.mjs prune-empty-changesets",
+      "",
+      "      - name: Create release PR or publish to npm",
+    ].join("\n"),
+    "release-alpha-train must prune empty changesets before Changesets decides whether to publish",
+  );
   assertContains(
     ciWorkflow,
     "node scripts/release-alpha-train.mjs status --published \"$PUBLISHED\" --remote false",

scripts/release-alpha-train.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { execFile as execFileCallback } from "node:child_process";
-import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { mkdir, readFile, readdir, unlink, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { promisify } from "node:util";
 
@@ -113,7 +113,10 @@ export async function inspectAlphaReleaseTrain(options = {}) {
   const tagName = `v${version}`;
   const image = `${SERVER_IMAGE_NAME}:${version}`;
   const title = `ZITADEL Alpha ${version}`;
-  const activeChangesets = await activeChangesetFiles(cwd, readdirFn);
+  const activeChangesets = await activeChangesetFiles(cwd, {
+    readFile: readFileFn,
+    readdir: readdirFn,
+  });
   const headCommit = await gitOutput(execFileFn, cwd, ["rev-parse", "HEAD"]);
   const tagCommit = await tagCommitFor(tagName, execFileFn, cwd);
   const tagExists = Boolean(tagCommit);
@@ -246,6 +249,26 @@ export async function tagExists(tagName, execFileFn = execFile, cwd = process.cw
   return Boolean(await tagCommitFor(tagName, execFileFn, cwd));
 }
 
+export async function pruneEmptyChangesets(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const readFileFn = options.readFile ?? readFile;
+  const readdirFn = options.readdir ?? readdir;
+  const unlinkFn = options.unlink ?? unlink;
+
+  const removed = [];
+  const files = await changesetMarkdownFiles(cwd, readdirFn);
+  for (const file of files) {
+    const path = join(cwd, ".changeset", file);
+    const content = await readFileFn(path, "utf8");
+    if (!changesetHasReleaseBump(content)) {
+      await unlinkFn(path);
+      removed.push(file);
+    }
+  }
+
+  return removed.sort();
+}
+
 export function renderAlphaReleaseNotes({ title, version, image, packages }) {
   const lines = [
     `# ${title}`,
@@ -286,8 +309,10 @@ export function renderAlphaReleaseNotes({ title, version, image, packages }) {
 
 export function parseAlphaReleaseArgs(args) {
   const command = args[0];
-  if (command !== "prepare" && command !== "status") {
-    throw new Error("Usage: release-alpha-train.mjs <status|prepare> [--out-dir <path>] [--published <true|false>]");
+  if (command !== "prepare" && command !== "status" && command !== "prune-empty-changesets") {
+    throw new Error(
+      "Usage: release-alpha-train.mjs <status|prepare|prune-empty-changesets> [--out-dir <path>] [--published <true|false>]",
+    );
   }
   const values = {};
   for (let index = 1; index < args.length; index += 1) {
@@ -310,7 +335,25 @@ function camelCase(value) {
   return value.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
 }
 
-async function activeChangesetFiles(cwd, readdirFn = readdir) {
+async function activeChangesetFiles(cwd, options = {}) {
+  const readFileFn = options.readFile ?? readFile;
+  const readdirFn = options.readdir ?? readdir;
+  const prereleaseChangesets = await prereleaseTrackedChangesets(cwd, readFileFn);
+  const files = await changesetMarkdownFiles(cwd, readdirFn);
+  const active = [];
+  for (const file of files) {
+    if (prereleaseChangesets.has(changesetSlug(file))) {
+      continue;
+    }
+    const content = await readFileFn(join(cwd, ".changeset", file), "utf8");
+    if (changesetHasReleaseBump(content)) {
+      active.push(file);
+    }
+  }
+  return active.sort();
+}
+
+async function changesetMarkdownFiles(cwd, readdirFn = readdir) {
   let entries = [];
   try {
     entries = await readdirFn(join(cwd, ".changeset"), { withFileTypes: true });
@@ -327,6 +370,51 @@ async function activeChangesetFiles(cwd, readdirFn = readdir) {
     .sort();
 }
 
+async function prereleaseTrackedChangesets(cwd, readFileFn = readFile) {
+  let preState;
+  try {
+    preState = JSON.parse(await readFileFn(join(cwd, ".changeset/pre.json"), "utf8"));
+  } catch (error) {
+    if (isMissingPath(error)) {
+      return new Set();
+    }
+    throw error;
+  }
+  if (!Array.isArray(preState.changesets)) {
+    return new Set();
+  }
+  return new Set(preState.changesets.filter((name) => typeof name === "string"));
+}
+
+function changesetSlug(file) {
+  return file.replace(/\.md$/, "");
+}
+
+function changesetHasReleaseBump(content) {
+  const frontmatter = changesetFrontmatter(content);
+  if (frontmatter === undefined) {
+    return true;
+  }
+  return frontmatter.split("\n").some((line) => {
+    const trimmed = line.trim();
+    return trimmed.length > 0 && !trimmed.startsWith("#");
+  });
+}
+
+function changesetFrontmatter(content) {
+  const normalized = content.replace(/\r\n/g, "\n");
+  if (!normalized.startsWith("---\n")) {
+    return undefined;
+  }
+  const lines = normalized.split("\n");
+  for (let index = 1; index < lines.length; index += 1) {
+    if (lines[index] === "---") {
+      return lines.slice(1, index).join("\n");
+    }
+  }
+  return undefined;
+}
+
 async function tagCommitFor(tagName, execFileFn = execFile, cwd = process.cwd()) {
   try {
     return await gitOutput(execFileFn, cwd, ["rev-list", "-n", "1", tagName]);
@@ -400,18 +488,26 @@ function printAlphaOutputs(result) {
   }
 }
 
+function printPrunedChangesets(files) {
+  console.log(`pruned_empty_changesets=${files.join(",")}`);
+}
+
 function isDirectRun(url) {
   return process.argv[1] && url === new URL(`file://${process.argv[1]}`).href;
 }
 
 if (isDirectRun(import.meta.url)) {
   try {
     const { command, values } = parseAlphaReleaseArgs(process.argv.slice(2));
-    const result =
-      command === "status"
-        ? await inspectAlphaReleaseTrain(values)
-        : await prepareAlphaReleaseTrain(values);
-    printAlphaOutputs(result);
+    if (command === "prune-empty-changesets") {
+      printPrunedChangesets(await pruneEmptyChangesets(values));
+    } else {
+      const result =
+        command === "status"
+          ? await inspectAlphaReleaseTrain(values)
+          : await prepareAlphaReleaseTrain(values);
+      printAlphaOutputs(result);
+    }
   } catch (error) {
     console.error(error instanceof Error ? error.message : String(error));
     process.exit(1);