@catladder/cli 0.0.0-main-8dbb6c76 → 0.0.0-main-a6b45abe

package/src/release/changesets.ts

@@ -0,0 +1,156 @@
+/**
+ * pure logic of the changesets release method (used by catci in CI):
+ * parsing `.changeset/*.md` files, computing the next version from the
+ * last release tag and rendering the changelog.
+ *
+ * Parsing uses the official `@changesets/parse` (the reference
+ * implementation of the format), so anything `yarn changeset` writes is
+ * read exactly — including quoted values, YAML comments and `none`
+ * markers. Unlike the official tooling, versions are NOT read from
+ * package.json: catladder projects are applications whose version lives
+ * in git tags (`vX.Y.Z`), and some have no root package.json at all —
+ * so the package names in the frontmatter are ignored and only the
+ * highest bump counts.
+ */
+import parseChangeset from "@changesets/parse";
+
+export const BUMPS = ["patch", "minor", "major"] as const;
+export type Bump = (typeof BUMPS)[number];
+
+const isBump = (type: string): type is Bump =>
+  (BUMPS as readonly string[]).includes(type);
+
+export type Changeset = {
+  fileName: string;
+  bump: Bump;
+  summary: string;
+};
+
+/**
+ * parses one changeset markdown file (official changesets format):
+ *
+ * ```
+ * ---
+ * "some-package": minor
+ * ---
+ *
+ * human-written summary
+ * ```
+ *
+ * The frontmatter is parsed by `@changesets/parse` (real YAML), then
+ * reduced to a single effective bump: `none` releases are dropped
+ * (they intentionally request no version change) and the highest of the
+ * rest wins. Throws on files that aren't valid changesets — a malformed
+ * file in `.changeset/` is a mistake worth failing the release over,
+ * not skipping silently.
+ */
+export const parseChangesetFile = (
+  fileName: string,
+  content: string,
+): Changeset => {
+  let parsed: ReturnType<typeof parseChangeset>;
+  try {
+    parsed = parseChangeset(content);
+  } catch (error) {
+    throw new Error(
+      `${fileName}: not a valid changeset (${error instanceof Error ? error.message : error})`,
+    );
+  }
+  // ignore `none` — it explicitly requests no release for that package
+  const bumps = parsed.releases.map((release) => release.type).filter(isBump);
+  if (bumps.length === 0) {
+    throw new Error(
+      `${fileName}: changeset declares no effective version bump (major|minor|patch)`,
+    );
+  }
+  const summary = parsed.summary.trim();
+  if (summary === "") {
+    throw new Error(`${fileName}: changeset has no summary`);
+  }
+  return { fileName, bump: maxBump(bumps), summary };
+};
+
+export const maxBump = (bumps: readonly Bump[]): Bump =>
+  bumps.reduce((max, bump) =>
+    BUMPS.indexOf(bump) > BUMPS.indexOf(max) ? bump : max,
+  );
+
+/**
+ * the next version, derived from the last release tag (like
+ * semantic-release does). No previous tag → first release 1.0.0
+ * (matching semantic-release's first release).
+ */
+export const getNextVersion = (lastTag: string | null, bump: Bump): string => {
+  if (lastTag === null) {
+    return "1.0.0";
+  }
+  const match = lastTag.match(/^v(\d+)\.(\d+)\.(\d+)$/);
+  if (!match) {
+    throw new Error(
+      `last release tag "${lastTag}" is not of the form vX.Y.Z — cannot derive the next version`,
+    );
+  }
+  const [major, minor, patch] = match.slice(1).map(Number);
+  switch (bump) {
+    case "major":
+      return `${major + 1}.0.0`;
+    case "minor":
+      return `${major}.${minor + 1}.0`;
+    case "patch":
+      return `${major}.${minor}.${patch + 1}`;
+  }
+};
+
+const BUMP_HEADINGS: Record<Bump, string> = {
+  major: "Major Changes",
+  minor: "Minor Changes",
+  patch: "Patch Changes",
+};
+
+/**
+ * the changelog entries for one release, grouped by bump level
+ * (mirroring the official changesets changelog layout), without the
+ * version heading — also used as the release commit body
+ */
+export const renderChangelogEntries = (
+  changesets: readonly Changeset[],
+): string =>
+  [...BUMPS]
+    .reverse()
+    .map((bump) => {
+      const entries = changesets.filter((changeset) => changeset.bump === bump);
+      if (entries.length === 0) return null;
+      return [
+        `### ${BUMP_HEADINGS[bump]}`,
+        "",
+        ...entries.map(
+          // indent multi-line summaries so they stay part of the bullet
+          (entry) => `- ${entry.summary.replace(/\r?\n/g, "\n  ")}`,
+        ),
+      ].join("\n");
+    })
+    .filter((section) => section !== null)
+    .join("\n\n");
+
+const CHANGELOG_HEADER = "# Changelog";
+
+/**
+ * prepends the release section to the changelog, keeping the
+ * `# Changelog` header on top
+ */
+export const prependToChangelog = (
+  existingContent: string | null,
+  version: string,
+  date: string,
+  entries: string,
+): string => {
+  const section = `## ${version} (${date})\n\n${entries}\n`;
+  const previous = (existingContent ?? "")
+    .replace(new RegExp(`^${CHANGELOG_HEADER}\\s*\\n`), "")
+    .trim();
+  return [
+    CHANGELOG_HEADER,
+    "",
+    section + (previous ? "\n" + previous + "\n" : ""),
+  ].join("\n");
+};

package/src/release/changesetsReleaseJob.ts

@@ -0,0 +1,208 @@
+/**
+ * the changesets release CI job (run by catci via the
+ * `changesetsRelease` script of the `changesets` job image):
+ * consumes pending `.changeset/*.md` files, bumps the version derived
+ * from the last `v*` tag, writes the changelog, commits, tags and
+ * pushes — the pushed tag triggers the taggedRelease pipeline.
+ */
+import { existsSync } from "fs";
+import { readFile, readdir, rm, writeFile } from "fs/promises";
+import { join } from "path";
+import type { Changeset } from "./changesets";
+import {
+  getNextVersion,
+  maxBump,
+  parseChangesetFile,
+  prependToChangelog,
+  renderChangelogEntries,
+} from "./changesets";
+import { ensureReleaseHistory, getLastReleaseTag, git } from "./releaseGit";
+import { appendStepSummary } from "./stepSummary";
+
+const CHANGESET_DIR = ".changeset";
+const CHANGELOG_FILE = "CHANGELOG.md";
+
+/**
+ * the generated taggedRelease workflow (dispatched after the tag push,
+ * see dispatchTaggedReleaseWorkflow). Keep in sync with
+ * `workflowFileName` in pipeline/src/backends/github/GithubBackend.ts.
+ */
+const GITHUB_TAGGED_RELEASE_WORKFLOW = "catladder-release.yml";
+
+export const readPendingChangesets = async () => {
+  const entries = await readdir(CHANGESET_DIR).catch(() => []);
+  const files = entries.filter(
+    (file) => file.endsWith(".md") && file.toLowerCase() !== "readme.md",
+  );
+  return Promise.all(
+    files.map(async (file) =>
+      parseChangesetFile(
+        file,
+        await readFile(join(CHANGESET_DIR, file), "utf-8"),
+      ),
+    ),
+  );
+};
+
+const ensureGitIdentity = async () => {
+  const email = await git("config", "user.email").catch(() => "");
+  if (email !== "") return;
+  const onGithub = process.env.GITHUB_ACTIONS === "true";
+  await git(
+    "config",
+    "user.name",
+    onGithub ? "github-actions[bot]" : "catladder",
+  );
+  await git(
+    "config",
+    "user.email",
+    onGithub
+      ? "41898282+github-actions[bot]@users.noreply.github.com"
+      : "catladder-release@panter.ch",
+  );
+};
+
+const requireEnv = (name: string): string => {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(`${name} is not set — cannot push the release`);
+  }
+  return value;
+};
+
+/**
+ * pushes the release commit and tag.
+ * - gitlab: CI checkouts have a read-only origin, so push via an
+ *   authenticated url with GL_TOKEN (the same project access token
+ *   semantic-release uses)
+ * - github: actions/checkout persists the job token credentials, so a
+ *   plain push to origin works (`permissions: contents: write`)
+ */
+const pushCommitAndTag = async (tag: string) => {
+  // --atomic: all refs or none — a rejected tag must not leave the
+  // release commit half-pushed (observed when a stale local view
+  // rederived an existing version)
+  if (process.env.GITHUB_ACTIONS === "true") {
+    const branch = requireEnv("GITHUB_REF_NAME");
+    await git("push", "--atomic", "origin", `HEAD:refs/heads/${branch}`, tag);
+    return;
+  }
+  const token = requireEnv("GL_TOKEN");
+  const host = requireEnv("CI_SERVER_HOST");
+  const projectPath = requireEnv("CI_PROJECT_PATH");
+  const branch = requireEnv("CI_COMMIT_BRANCH");
+  const remote = `https://oauth2:${token}@${host}/${projectPath}.git`;
+  await git("push", "--atomic", remote, `HEAD:refs/heads/${branch}`, tag);
+};
+
+/**
+ * tags pushed with the default GITHUB_TOKEN do not trigger `on: push:
+ * tags` workflows (github's recursion guard), so the taggedRelease
+ * workflow is dispatched explicitly for the new tag
+ * (`permissions: actions: write`; workflow_dispatch created BY the
+ * token does run)
+ */
+export const dispatchTaggedReleaseWorkflow = async (tag: string) => {
+  const apiUrl = process.env.GITHUB_API_URL ?? "https://api.github.com";
+  const repository = requireEnv("GITHUB_REPOSITORY");
+  const token = requireEnv("GITHUB_TOKEN");
+  const response = await fetch(
+    `${apiUrl}/repos/${repository}/actions/workflows/${GITHUB_TAGGED_RELEASE_WORKFLOW}/dispatches`,
+    {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${token}`,
+        accept: "application/vnd.github+json",
+      },
+      body: JSON.stringify({ ref: tag }),
+    },
+  );
+  if (!response.ok) {
+    throw new Error(
+      `dispatching ${GITHUB_TAGGED_RELEASE_WORKFLOW} for ${tag} failed: ${response.status} ${await response.text()}`,
+    );
+  }
+  console.log(`dispatched ${GITHUB_TAGGED_RELEASE_WORKFLOW} for ${tag}`);
+};
+
+/**
+ * the escape hatch of the force-release job: releasing without pending
+ * changesets (e.g. a hotfix merged without one) must not require a new
+ * MR, so a forced empty release becomes a patch bump with a generic
+ * changelog entry instead of a no-op
+ */
+const FORCED_RELEASE_CHANGESET: Changeset = {
+  fileName: "",
+  bump: "patch",
+  summary: "Forced release without pending changesets.",
+};
+
+export const changesetsReleaseJob = async () => {
+  const pending = await readPendingChangesets();
+  const forcedEmpty =
+    pending.length === 0 && process.env.CATLADDER_FORCE_RELEASE === "true";
+  if (pending.length === 0 && !forcedEmpty) {
+    console.log(
+      `no changesets found in ${CHANGESET_DIR}/ — nothing to release`,
+    );
+    console.log(
+      `add one with \`${existsSync("pnpm-lock.yaml") ? "pnpm" : "yarn"} changeset\` (or write .changeset/<name>.md by hand) and merge it to release`,
+    );
+    console.log(
+      "to release anyway (patch bump), run the force release job instead",
+    );
+    appendStepSummary(
+      `ℹ️ **Nothing released** — no pending changesets in \`${CHANGESET_DIR}/\`. ` +
+        "Merge a changeset and release again, or force the release for a patch bump.",
+    );
+    return;
+  }
+  const changesets = forcedEmpty ? [FORCED_RELEASE_CHANGESET] : pending;
+  if (forcedEmpty) {
+    console.log("no changesets pending — forced release, bumping a patch");
+  }
+
+  await ensureReleaseHistory();
+  const lastTag = await getLastReleaseTag();
+  const version = getNextVersion(
+    lastTag,
+    maxBump(changesets.map((c) => c.bump)),
+  );
+  const tag = `v${version}`;
+  console.log(
+    `releasing ${tag} (${lastTag ?? "first release"} + ${changesets.length} changeset(s))`,
+  );
+
+  const entries = renderChangelogEntries(changesets);
+  const existingChangelog = await readFile(CHANGELOG_FILE, "utf-8").catch(
+    () => null,
+  );
+  const date = new Date().toISOString().slice(0, 10);
+  await writeFile(
+    CHANGELOG_FILE,
+    prependToChangelog(existingChangelog, version, date, entries),
+  );
+  await Promise.all(
+    // pending, not changesets: the synthetic forced-release changeset
+    // has no file to delete
+    pending.map((changeset) => rm(join(CHANGESET_DIR, changeset.fileName))),
+  );
+
+  await ensureGitIdentity();
+  // a forced empty release consumes no changeset files — and .changeset/
+  // may not even exist yet, which `git add` would reject
+  if (forcedEmpty) {
+    await git("add", CHANGELOG_FILE);
+  } else {
+    await git("add", CHANGELOG_FILE, CHANGESET_DIR);
+  }
+  await git("commit", "-m", `chore(release): ${version}\n\n${entries}`);
+  await git("tag", tag);
+  await pushCommitAndTag(tag);
+  console.log(`released ${tag}`);
+  appendStepSummary(`🚀 **Released ${tag}**\n\n${entries}`);
+
+  if (process.env.GITHUB_ACTIONS === "true") {
+    await dispatchTaggedReleaseWorkflow(tag);
+  }
+};

package/src/release/githubQueuedRelease.ts

@@ -0,0 +1,207 @@
+/**
+ * "release once the pipeline succeeds" on github.
+ *
+ * gitlab expresses this natively inside the pipeline (the `create
+ * release` button job plus an executor with `needs` on the whole
+ * pipeline); github has no cross-workflow needs, so catladder uses a
+ * marker ref plus a workflow_run-triggered workflow instead:
+ *
+ * - the manual `create-release` dispatch runs `github-queue-check`:
+ *   - the main workflow run for HEAD completed green (or never ran) →
+ *     release right away (queued=false, the job's release step runs)
+ *   - still running → push the marker ref and stop (queued=true skips
+ *     the release step); the release-on-green workflow takes over
+ *   - completed red → fail with a pointer to the force task
+ * - the release-on-green workflow (`on: workflow_run` of the main
+ *   workflow) runs `github-queued-guard` on every completed main run:
+ *   it consumes the marker when it matches the run's head sha and
+ *   releases only when the run concluded green
+ */
+import { appendFileSync } from "fs";
+import { git } from "./releaseGit";
+import { appendStepSummary, workflowLink } from "./stepSummary";
+
+/**
+ * the generated main-branch workflow whose runs gate a queued release.
+ * Keep in sync with `workflowFileName` / GENERATED_FILE_PREFIX in
+ * pipeline/src/backends/github/GithubBackend.ts.
+ */
+const GITHUB_MAIN_WORKFLOW = "catladder-main.yml";
+
+/**
+ * the workflow that picks up a queued release, for summary links. Keep
+ * in sync with the release-on-green file name in
+ * pipeline/src/backends/github/GithubBackend.ts.
+ */
+const GITHUB_ON_GREEN_WORKFLOW = "catladder-release-on-green.yml";
+
+/**
+ * where a queued release is recorded: a ref outside refs/heads and
+ * refs/tags, pointing at the commit the release was queued for.
+ * Writable with the job token (`permissions: contents: write`).
+ */
+const QUEUE_MARKER_REF = "refs/catladder/release-queued";
+
+/**
+ * github container jobs: the workspace volume is owned by the host
+ * runner user while catci runs as the container user — git refuses the
+ * repo ("dubious ownership") without a safe.directory entry. The
+ * release entrypoint scripts do the same, but the queue commands run
+ * before them.
+ */
+const ensureGitSafeDirectory = async () => {
+  await git("config", "--global", "--add", "safe.directory", process.cwd());
+};
+
+const requireEnv = (name: string): string => {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(`${name} is not set`);
+  }
+  return value;
+};
+
+const fail = (message: string): never => {
+  console.error(message);
+  process.exit(1);
+};
+
+/**
+ * step outputs of the github-actions step running the command
+ * (`$GITHUB_OUTPUT` is always set in workflow steps)
+ */
+const setStepOutput = (name: string, value: string) => {
+  const file = process.env.GITHUB_OUTPUT;
+  if (!file) {
+    return;
+  }
+  appendFileSync(file, `${name}=${value}\n`);
+};
+
+const getMainWorkflowRun = async (
+  sha: string,
+): Promise<{ status: string; conclusion: string | null } | null> => {
+  const apiUrl = process.env.GITHUB_API_URL ?? "https://api.github.com";
+  const repository = requireEnv("GITHUB_REPOSITORY");
+  const token = requireEnv("GITHUB_TOKEN");
+  const response = await fetch(
+    `${apiUrl}/repos/${repository}/actions/workflows/${GITHUB_MAIN_WORKFLOW}/runs?head_sha=${sha}&per_page=5`,
+    {
+      headers: {
+        authorization: `Bearer ${token}`,
+        accept: "application/vnd.github+json",
+      },
+    },
+  );
+  if (!response.ok) {
+    throw new Error(
+      `listing ${GITHUB_MAIN_WORKFLOW} runs failed: ${response.status} ${await response.text()}`,
+    );
+  }
+  const data = (await response.json()) as {
+    workflow_runs?: Array<{ status: string; conclusion: string | null }>;
+  };
+  // newest first — re-runs replace older attempts
+  return data.workflow_runs?.[0] ?? null;
+};
+
+/**
+ * `catci release github-queue-check` — first step of the manual
+ * create-release dispatch job. Decides between releasing right away
+ * (queued=false) and queueing for the running main workflow
+ * (queued=true).
+ */
+export const githubQueueCheckJob = async () => {
+  await ensureGitSafeDirectory();
+  const sha = await git("rev-parse", "HEAD");
+  const run = await getMainWorkflowRun(sha);
+  if (!run) {
+    console.log(`no main workflow run found for ${sha} — releasing right away`);
+    appendStepSummary(
+      `ℹ️ No main workflow run found for \`${sha}\` — releasing right away.`,
+    );
+    setStepOutput("queued", "false");
+    return;
+  }
+  if (run.status === "completed") {
+    if (run.conclusion === "success") {
+      console.log(`main workflow for ${sha} succeeded — releasing right away`);
+      appendStepSummary(
+        `✅ The main workflow for \`${sha}\` succeeded — releasing right away.`,
+      );
+      setStepOutput("queued", "false");
+      return;
+    }
+    appendStepSummary(
+      `❌ Not releasing: the ${workflowLink(GITHUB_MAIN_WORKFLOW, "main workflow")} run for \`${sha}\` concluded **${run.conclusion}**. ` +
+        `Fix the pipeline, or re-run with the force checkbox to release anyway.`,
+    );
+    fail(
+      `the main workflow for ${sha} concluded '${run.conclusion}' — ` +
+        `fix the pipeline, or force the release to release anyway`,
+    );
+  }
+  // queued / in_progress / waiting: record the intent and let the
+  // release-on-green workflow do the release. Force-push: a re-queue
+  // (or a stale marker of an older commit) just moves the marker.
+  await git("push", "origin", `+${sha}:${QUEUE_MARKER_REF}`);
+  const runState = run.status.replace(/_/g, " ");
+  console.log(
+    `main workflow for ${sha} is ${runState} — release queued: ` +
+      `the 'release on green' workflow creates the release as soon as the run succeeds`,
+  );
+  appendStepSummary(
+    `⏳ **Release queued** for \`${sha}\` — the ${workflowLink(GITHUB_MAIN_WORKFLOW, "main workflow")} run is still ${runState}. ` +
+      `${workflowLink(GITHUB_ON_GREEN_WORKFLOW, "release on green")} creates the release as soon as it succeeds.`,
+  );
+  setStepOutput("queued", "true");
+};
+
+/**
+ * `catci release github-queued-guard <head-sha> <conclusion>` — guard
+ * step of the release-on-green workflow, running on every completed
+ * main workflow run. Consumes the marker when it matches the run and
+ * decides whether the release step runs (release=true).
+ */
+export const githubQueuedGuardJob = async (
+  headSha: string,
+  conclusion: string,
+) => {
+  await ensureGitSafeDirectory();
+  const markerLine = await git("ls-remote", "origin", QUEUE_MARKER_REF);
+  const marker = markerLine.split(/\s+/)[0] ?? "";
+  if (!marker) {
+    console.log("no release queued — nothing to do");
+    appendStepSummary("No release queued — nothing to do.");
+    setStepOutput("release", "false");
+    return;
+  }
+  if (marker !== headSha) {
+    console.log(
+      `queued release is for ${marker}, this run is for ${headSha} — leaving the queue untouched`,
+    );
+    appendStepSummary(
+      `Queued release is for \`${marker}\`, this run is for \`${headSha}\` — leaving the queue untouched.`,
+    );
+    setStepOutput("release", "false");
+    return;
+  }
+  // consume the marker either way: the queued intent applied to exactly
+  // this run, whatever its outcome
+  await git("push", "origin", `:${QUEUE_MARKER_REF}`);
+  if (conclusion !== "success") {
+    appendStepSummary(
+      `❌ Queued release for \`${headSha}\` **not executed**: the main workflow concluded **${conclusion}**. ` +
+        `Fix the pipeline and queue again via the 🚀 create release workflow.`,
+    );
+    fail(
+      `queued release not executed: the main workflow concluded '${conclusion}' — ` +
+        `fix the pipeline and queue the release again`,
+    );
+  }
+  console.log(`main workflow for ${headSha} succeeded — releasing`);
+  appendStepSummary(
+    `✅ Main workflow for \`${headSha}\` succeeded — running the queued release.`,
+  );
+  setStepOutput("release", "true");
+};

package/src/release/releaseGit.ts

@@ -0,0 +1,47 @@
+/**
+ * git helpers shared by the release-related catci jobs (changesets
+ * release, changeset check).
+ */
+import { execFile as execFileCb } from "child_process";
+import { promisify } from "util";
+
+const execFile = promisify(execFileCb);
+
+export const git = async (...args: string[]): Promise<string> => {
+  const { stdout } = await execFile("git", args);
+  return stdout.trim();
+};
+
+/**
+ * CI checkouts are usually shallow and tagless (gitlab clones with
+ * depth 1; github's checkout needs fetch-depth: 0) — the local history
+ * then cannot answer "nearest v* tag" and the job would rederive the
+ * FIRST release version. Deepen and fetch tags before deriving.
+ */
+export const ensureReleaseHistory = async () => {
+  const shallow = await git("rev-parse", "--is-shallow-repository").catch(
+    () => "false",
+  );
+  try {
+    if (shallow === "true") {
+      await git("fetch", "--quiet", "--unshallow", "--tags", "origin");
+    } else {
+      await git("fetch", "--quiet", "--tags", "origin");
+    }
+  } catch (e) {
+    console.warn(
+      `could not fetch tags from origin (${e}) — version derivation may be wrong on a shallow clone`,
+    );
+  }
+};
+
+export const getLastReleaseTag = async (): Promise<string | null> => {
+  try {
+    // the nearest v* tag in the history of HEAD — on hotfix branches
+    // this is deliberately the branch's own release line, not the
+    // globally highest version
+    return await git("describe", "--tags", "--abbrev=0", "--match", "v[0-9]*");
+  } catch {
+    return null;
+  }
+};

package/src/release/stepSummary.ts

@@ -0,0 +1,27 @@
+/**
+ * github step summaries: markdown shown on the run page, so a run
+ * explains what happened without reading job logs. No-op outside
+ * github actions (GITHUB_STEP_SUMMARY unset, e.g. on gitlab).
+ */
+import { appendFileSync } from "fs";
+
+export const appendStepSummary = (markdown: string) => {
+  const file = process.env.GITHUB_STEP_SUMMARY;
+  if (!file) {
+    return;
+  }
+  appendFileSync(file, markdown + "\n");
+};
+
+/**
+ * link to a generated workflow's run list (e.g.
+ * `workflowLink("catladder-main.yml", "catladder main")`)
+ */
+export const workflowLink = (fileName: string, label: string): string => {
+  const server = process.env.GITHUB_SERVER_URL ?? "https://github.com";
+  const repository = process.env.GITHUB_REPOSITORY;
+  if (!repository) {
+    return label;
+  }
+  return `[${label}](${server}/${repository}/actions/workflows/${fileName})`;
+};