fix(release): Sync GitHub release notes with changelog

Generate GitHub release bodies from CHANGELOG.md and use them in the\nrelease workflow instead of a static release body.\n\nWhen the latest changelog section is [Unreleased], promote it to the\ntarget release version during release preparation so release notes are\nconsistent and validation succeeds.\n\nKeep dry-run behavior non-mutating by preparing changelog updates in a\ntemporary file only.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: cameroncooke

.github/workflows/release.yml

@@ -72,6 +72,13 @@ jobs:
             # For tag-based releases, package.json was already updated by release script
           fi
 
+      - name: Generate GitHub release notes (production releases only)
+        if: github.event_name == 'push'
+        run: |
+          node scripts/generate-github-release-notes.mjs \
+            --version "${{ steps.get_version.outputs.VERSION }}" \
+            --out github-release-body.md
+
       - name: Create package
         run: npm pack
 
@@ -122,20 +129,7 @@ jobs:
         with:
           tag_name: v${{ steps.get_version.outputs.VERSION }}
           name: Release v${{ steps.get_version.outputs.VERSION }}
-          body: |
-            ## Release v${{ steps.get_version.outputs.VERSION }}
-
-            ### Installation
-            ```bash
-            npm install -g xcodebuildmcp@${{ steps.get_version.outputs.VERSION }}
-            ```
-
-            Or use with npx:
-            ```bash
-            npx xcodebuildmcp@${{ steps.get_version.outputs.VERSION }}
-            ```
-
-            📦 **NPM Package**: https://www.npmjs.com/package/xcodebuildmcp/v/${{ steps.get_version.outputs.VERSION }}
+          body_path: github-release-body.md
           files: |
             xcodebuildmcp-${{ steps.get_version.outputs.VERSION }}.tgz
           draft: false

docs/dev/RELEASE_PROCESS.md

@@ -1,5 +1,22 @@
 # Release Process
 
+## GitHub Release Notes Source of Truth
+
+GitHub release descriptions are generated from the matching version section in `CHANGELOG.md`. The release process now enforces this in both local and CI flows:
+
+- `scripts/release.sh` validates release notes generation before tagging and pushing
+- `.github/workflows/release.yml` generates the final GitHub release body from `CHANGELOG.md`
+
+If the changelog section for the target version is missing or empty, release execution fails with a clear error.
+
+If the latest changelog section is `## [Unreleased]` and no matching version heading exists yet, `scripts/release.sh` automatically renames that heading to `## [<version>]` for the release. In `--dry-run`, this rename is performed only in a temporary file and does not modify `CHANGELOG.md`.
+
+Preview release notes locally:
+
+```bash
+node scripts/generate-github-release-notes.mjs --version 2.0.0-beta.1
+```
+
 ## Step-by-Step Development Workflow
 
 ### 1. Starting New Work

scripts/generate-github-release-notes.mjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+
+import { readFile, writeFile } from 'node:fs/promises';
+import process from 'node:process';
+
+const VERSION_HEADING_REGEX = /^##\s+\[([^\]]+)\](?:\s+-\s+.*)?\s*$/;
+
+function normalizeVersion(value) {
+  return value.trim().replace(/^v/, '');
+}
+
+function parseArgs(argv) {
+  const args = {
+    changelog: 'CHANGELOG.md',
+    out: '',
+    packageName: 'xcodebuildmcp',
+    version: '',
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const next = argv[i + 1];
+
+    if (arg === '--version') {
+      if (!next) {
+        throw new Error('Missing value for --version');
+      }
+      args.version = next;
+      i += 1;
+      continue;
+    }
+
+    if (arg === '--changelog') {
+      if (!next) {
+        throw new Error('Missing value for --changelog');
+      }
+      args.changelog = next;
+      i += 1;
+      continue;
+    }
+
+    if (arg === '--out') {
+      if (!next) {
+        throw new Error('Missing value for --out');
+      }
+      args.out = next;
+      i += 1;
+      continue;
+    }
+
+    if (arg === '--package') {
+      if (!next) {
+        throw new Error('Missing value for --package');
+      }
+      args.packageName = next;
+      i += 1;
+      continue;
+    }
+
+    if (arg === '--help' || arg === '-h') {
+      printHelp();
+      process.exit(0);
+    }
+
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  if (!args.version) {
+    throw new Error('Missing required argument: --version');
+  }
+
+  return args;
+}
+
+function printHelp() {
+  console.log(`Generate GitHub release notes from CHANGELOG.md.
+
+Usage:
+  node scripts/generate-github-release-notes.mjs --version <version> [options]
+
+Options:
+  --version <version>    Required release version (e.g. 2.0.0 or 2.0.0-beta.1)
+  --changelog <path>     Changelog path (default: CHANGELOG.md)
+  --out <path>           Output file path (default: stdout)
+  --package <name>       Package name for install snippets (default: xcodebuildmcp)
+  -h, --help             Show this help
+`);
+}
+
+function extractChangelogSection(changelog, version) {
+  const normalizedTarget = normalizeVersion(version);
+  const lines = changelog.split(/\r?\n/);
+  let sectionStartLine = -1;
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const match = lines[index].match(VERSION_HEADING_REGEX);
+    if (!match) {
+      continue;
+    }
+
+    if (normalizeVersion(match[1]) === normalizedTarget) {
+      sectionStartLine = index + 1;
+      break;
+    }
+  }
+
+  if (sectionStartLine === -1) {
+    throw new Error(
+      `Missing CHANGELOG section for version: ${normalizedTarget}\n` +
+        `Add a heading like: ## [${normalizedTarget}] (or ## [v${normalizedTarget}] - YYYY-MM-DD)`
+    );
+  }
+
+  let sectionEndLine = lines.length;
+  for (let index = sectionStartLine; index < lines.length; index += 1) {
+    if (VERSION_HEADING_REGEX.test(lines[index])) {
+      sectionEndLine = index;
+      break;
+    }
+  }
+
+  const section = lines.slice(sectionStartLine, sectionEndLine).join('\n').trim();
+  if (!section) {
+    throw new Error(`CHANGELOG section for version ${normalizedTarget} is empty`);
+  }
+
+  return section;
+}
+
+function buildInstallAndSetupSection(version, packageName) {
+  const normalizedVersion = normalizeVersion(version);
+  return [
+    '### CLI Installation',
+    '```bash',
+    `npm install -g ${packageName}@${normalizedVersion}`,
+    `${packageName} --help`,
+    '```',
+    '',
+    '### MCP Setup',
+    '```json',
+    '"XcodeBuildMCP": {',
+    '  "command": "npx",',
+    `  "args": ["-y", "${packageName}@${normalizedVersion}", "mcp"]`,
+    '}',
+    '```',
+    '',
+    `📦 **NPM Package**: https://www.npmjs.com/package/${packageName}/v/${normalizedVersion}`,
+  ].join('\n');
+}
+
+function buildReleaseBody(version, changelogSection, packageName) {
+  const normalizedVersion = normalizeVersion(version);
+  const installAndSetup = buildInstallAndSetupSection(normalizedVersion, packageName);
+  return [
+    `## Release v${normalizedVersion}`,
+    '',
+    changelogSection,
+    '',
+    installAndSetup,
+    '',
+  ].join('\n');
+}
+
+async function main() {
+  try {
+    const { changelog, out, packageName, version } = parseArgs(process.argv.slice(2));
+    const changelogContent = await readFile(changelog, 'utf8').catch(() => {
+      throw new Error(`Could not read CHANGELOG.md at ${changelog}`);
+    });
+
+    const section = extractChangelogSection(changelogContent, version);
+    const body = buildReleaseBody(version, section, packageName);
+
+    if (out) {
+      await writeFile(out, body, 'utf8');
+      return;
+    }
+
+    process.stdout.write(body);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`❌ ${message}\n`);
+    process.exit(1);
+  }
+}
+
+await main();

scripts/release.sh

@@ -270,6 +270,57 @@ sed_inplace() {
   fi
 }
 
+prepare_changelog_for_release_notes() {
+  local source_path="$1"
+  local destination_path="$2"
+  local target_version="$3"
+
+  node - "$source_path" "$destination_path" "$target_version" <<'NODE'
+const fs = require('fs');
+
+const [sourcePath, destinationPath, targetVersion] = process.argv.slice(2);
+const versionHeadingRegex = /^##\s+\[([^\]]+)\](?:\s+-\s+.*)?\s*$/;
+const normalizeVersion = (value) => value.trim().replace(/^v/, '');
+
+try {
+  const changelog = fs.readFileSync(sourcePath, 'utf8');
+  const lines = changelog.split(/\r?\n/);
+  const normalizedTargetVersion = normalizeVersion(targetVersion);
+  let firstHeadingIndex = -1;
+  let firstHeadingLabel = '';
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const match = lines[index].match(versionHeadingRegex);
+    if (!match) {
+      continue;
+    }
+
+    const label = match[1].trim();
+    if (normalizeVersion(label) === normalizedTargetVersion) {
+      process.exit(3);
+    }
+
+    if (firstHeadingIndex === -1) {
+      firstHeadingIndex = index;
+      firstHeadingLabel = label;
+    }
+  }
+
+  if (firstHeadingIndex === -1 || firstHeadingLabel !== 'Unreleased') {
+    process.exit(3);
+  }
+
+  lines[firstHeadingIndex] = lines[firstHeadingIndex].replace('[Unreleased]', `[${targetVersion}]`);
+  fs.writeFileSync(destinationPath, `${lines.join('\n')}\n`, 'utf8');
+  process.exit(0);
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`❌ Failed to prepare changelog for release notes: ${message}`);
+  process.exit(1);
+}
+NODE
+}
+
 # Ensure we're in the project root (parent of scripts directory)
 cd "$(dirname "$0")/.."
 
@@ -286,6 +337,48 @@ else
   fi
 fi
 
+CHANGELOG_PATH="CHANGELOG.md"
+CHANGELOG_FOR_VALIDATION="$CHANGELOG_PATH"
+CHANGELOG_VALIDATION_TEMP=""
+CHANGELOG_RENAMED_ON_DISK=false
+
+if $DRY_RUN; then
+  CHANGELOG_VALIDATION_TEMP=$(mktemp "${TMPDIR:-/tmp}/xcodebuildmcp-changelog-validation.XXXXXX")
+  if prepare_changelog_for_release_notes "$CHANGELOG_PATH" "$CHANGELOG_VALIDATION_TEMP" "$VERSION"; then
+    CHANGELOG_FOR_VALIDATION="$CHANGELOG_VALIDATION_TEMP"
+    echo "ℹ️  Dry-run: prepared release changelog from [Unreleased] in a temp file."
+  else
+    PREPARE_STATUS=$?
+    if [[ $PREPARE_STATUS -eq 3 ]]; then
+      rm "$CHANGELOG_VALIDATION_TEMP"
+      CHANGELOG_VALIDATION_TEMP=""
+    else
+      rm "$CHANGELOG_VALIDATION_TEMP"
+      exit $PREPARE_STATUS
+    fi
+  fi
+else
+  if prepare_changelog_for_release_notes "$CHANGELOG_PATH" "$CHANGELOG_PATH" "$VERSION"; then
+    CHANGELOG_RENAMED_ON_DISK=true
+    echo "📝 Renamed CHANGELOG heading [Unreleased] -> [$VERSION]"
+  else
+    PREPARE_STATUS=$?
+    if [[ $PREPARE_STATUS -ne 3 ]]; then
+      exit $PREPARE_STATUS
+    fi
+  fi
+fi
+
+echo ""
+echo "🧾 Validating CHANGELOG release notes for v$VERSION..."
+RELEASE_NOTES_TMP=$(mktemp "${TMPDIR:-/tmp}/xcodebuildmcp-release-notes.XXXXXX")
+node scripts/generate-github-release-notes.mjs --version "$VERSION" --changelog "$CHANGELOG_FOR_VALIDATION" --out "$RELEASE_NOTES_TMP"
+rm "$RELEASE_NOTES_TMP"
+if [[ -n "$CHANGELOG_VALIDATION_TEMP" ]]; then
+  rm "$CHANGELOG_VALIDATION_TEMP"
+fi
+echo "✅ CHANGELOG entry found and release notes generated."
+
 # Check if package.json already has this version (from previous attempt)
 CURRENT_PACKAGE_VERSION=$(node -p "require('./package.json').version")
 if [[ "$CURRENT_PACKAGE_VERSION" == "$VERSION" ]]; then
@@ -351,9 +444,9 @@ if [[ "$SKIP_VERSION_UPDATE" == "false" ]]; then
   echo ""
   echo "📦 Committing version changes..."
   if [[ -f server.json ]]; then
-    run git add package.json package-lock.json README.md docs/SKILLS.md server.json
+    run git add package.json package-lock.json README.md docs/SKILLS.md CHANGELOG.md server.json
   else
-    run git add package.json package-lock.json README.md docs/SKILLS.md
+    run git add package.json package-lock.json README.md docs/SKILLS.md CHANGELOG.md
   fi
   run git commit -m "Release v$VERSION"
 else
@@ -368,6 +461,12 @@ else
       run git commit -m "Align server.json for v$VERSION"
     fi
   fi
+
+  if $CHANGELOG_RENAMED_ON_DISK; then
+    echo "📝 Committing changelog release heading update..."
+    run git add CHANGELOG.md
+    run git commit -m "Finalize changelog for v$VERSION"
+  fi
 fi
 
 # Create or recreate tag at current HEAD