glab-setup-git-identity 0.6.0

package/docs/case-studies/issue-3/README.md

@@ -0,0 +1,338 @@
+# Case Study: Issue #3 - Release Formatting Script Only Handles Patch Changes
+
+## Issue Overview
+
+**Issue:** [#3](https://github.com/link-foundation/js-ai-driven-development-pipeline-template/issues/3)
+**Title:** Release formatting script only handles Patch changes, not Minor/Major
+**Status:** In Progress
+**Created:** 2025-12-17
+
+### Problem Statement
+
+The `scripts/format-release-notes.mjs` script only handles `### Patch Changes` sections, causing it to fail on Minor and Major releases.
+
+**Current Behavior:**
+
+- Section headers (### Minor Changes, ### Major Changes) remain in release notes
+- PR detection is skipped
+- Release formatting fails silently
+
+**Expected Behavior:**
+
+- Release notes should be formatted cleanly without section headers
+- PR detection should work for all release types
+- NPM badge should be added
+
+## Timeline of Events
+
+### December 13, 2025
+
+1. **Initial commit** - Template repository created with format-release-notes.mjs script
+2. **Release v0.1.0 created** - First release with Minor Changes section
+3. **Bug manifested** - Release shows "### Minor Changes" header and no PR link
+
+### December 16, 2025
+
+1. **Bug discovered in link-assistant/agent** - Issue #58 reported in downstream repository
+2. **Fix implemented** - PR #59 created with solution
+3. **Case study documented** - Comprehensive analysis in docs/case-studies/issue-58/
+
+### December 17, 2025
+
+1. **03:45 UTC** - Issue #3 created in template repository
+2. **03:47 UTC** - Comment added requesting:
+   - Find all repositories with same issue
+   - Create issues in those repositories
+   - Compile comprehensive case study in docs/case-studies/issue-3/
+   - Reconstruct timeline and root causes
+   - Propose solutions
+
+## Data Collection
+
+### Affected Repositories
+
+Search revealed 4 repositories with the same script:
+
+1. **link-foundation/js-ai-driven-development-pipeline-template** (this repo)
+   - Path: scripts/format-release-notes.mjs
+   - URL: https://github.com/link-foundation/js-ai-driven-development-pipeline-template
+
+2. **link-foundation/test-anywhere**
+   - Path: scripts/format-release-notes.mjs
+   - URL: https://github.com/link-foundation/test-anywhere
+
+3. **link-foundation/gh-download-pull-request**
+   - Path: scripts/format-release-notes.mjs
+   - URL: https://github.com/link-foundation/gh-download-pull-request
+
+4. **link-foundation/gh-download-issue**
+   - Path: scripts/format-release-notes.mjs
+   - URL: https://github.com/link-foundation/gh-download-issue
+
+### Release v0.1.0 Data
+
+**Release:** https://github.com/link-foundation/js-ai-driven-development-pipeline-template/releases/tag/v0.1.0
+
+**Current Body (Problematic):**
+
+```markdown
+### Minor Changes
+
+- 65d76dc: Initial template setup with complete AI-driven development pipeline
+
+  Features:
+  - Multi-runtime support for Node.js, Bun, and Deno
+  - Universal testing with test-anywhere framework
+  - Automated release workflow with changesets
+  - GitHub Actions CI/CD pipeline with 9 test combinations
+  - Code quality tools: ESLint + Prettier with Husky pre-commit hooks
+  - Package manager agnostic design
+```
+
+**CHANGELOG.md Content:**
+
+```markdown
+## 0.1.0
+
+### Minor Changes
+
+- 65d76dc: Initial template setup with complete AI-driven development pipeline
+
+  Features:
+  - Multi-runtime support for Node.js, Bun, and Deno
+  - Universal testing with test-anywhere framework
+  - Automated release workflow with changesets
+  - GitHub Actions CI/CD pipeline with 9 test combinations
+  - Code quality tools: ESLint + Prettier with Husky pre-commit hooks
+  - Package manager agnostic design
+```
+
+## Root Cause Analysis
+
+### Bug #1: Incorrect Section Header Remaining
+
+**File:** `scripts/format-release-notes.mjs`
+**Lines:** 92-115
+
+The script only matches `### Patch Changes` sections:
+
+```javascript
+const patchChangesMatchWithHash = currentBody.match(
+  /### Patch Changes\s*\n\s*-\s+([a-f0-9]+):\s+(.+?)$/s
+);
+const patchChangesMatchNoHash = currentBody.match(
+  /### Patch Changes\s*\n\s*-\s+(.+?)$/s
+);
+```
+
+**Root Cause:**
+
+- The regex pattern is hardcoded to only match `### Patch Changes`
+- When a release contains `### Minor Changes` or `### Major Changes`, the pattern doesn't match
+- Script exits early with warning message (line 113)
+- Section header remains in the release notes unprocessed
+
+### Bug #2: Missing PR Link
+
+**Related to Bug #1**
+
+Because the script exits early when it can't parse the changes section:
+
+- Commit hash is never extracted (lines 106-115)
+- PR detection logic is never reached (lines 136-182)
+- No PR link is added to release notes
+
+### Bug #3: Missing NPM Badge
+
+**Related to Bug #1**
+
+The NPM badge formatting (lines 184-195) is also never reached:
+
+- Script exits before building formatted body
+- No shields.io badge is added
+
+## Comparison with Changesets Default Behavior
+
+### Changesets CHANGELOG Format
+
+Changesets CLI generates CHANGELOG.md with section headers for organizational purposes:
+
+- `### Major Changes` - Breaking changes (X.0.0)
+- `### Minor Changes` - New features (0.X.0)
+- `### Patch Changes` - Bug fixes (0.0.X)
+
+**Sources:**
+
+- [Changesets GitHub Repository](https://github.com/changesets/changesets)
+- [Changesets Detailed Documentation](https://github.com/changesets/changesets/blob/main/docs/detailed-explanation.md)
+- [NPM Package](https://www.npmjs.com/package/@changesets/cli)
+- [LogRocket Guide to Changesets](https://blog.logrocket.com/version-management-changesets/)
+
+### Why This is a Problem for GitHub Releases
+
+1. **CHANGELOG.md vs GitHub Releases** - Section headers are useful in CHANGELOG.md for organizing multiple version entries, but redundant in individual GitHub Releases
+2. **Version already indicates type** - A v0.1.0 release is clearly a minor version; the "### Minor Changes" header is redundant
+3. **User expectations** - GitHub Release notes should be clean, concise, and focused on content, not categorization
+
+## Reference Implementation
+
+### link-assistant/agent Fix
+
+The bug was already fixed in a downstream repository:
+
+- **Repository:** link-assistant/agent
+- **Issue:** [#58](https://github.com/link-assistant/agent/issues/58)
+- **Pull Request:** [#59](https://github.com/link-assistant/agent/pull/59)
+- **Case Study:** docs/case-studies/issue-58/README.md
+
+### The Solution
+
+Replace hardcoded `### Patch Changes` regex with flexible pattern matching:
+
+```javascript
+// Match any changeset type (Major, Minor, or Patch)
+const changesPattern =
+  /### (Major|Minor|Patch) Changes\s*\n\s*-\s+(?:([a-f0-9]+):\s+)?(.+?)$/s;
+const changesMatch = currentBody.match(changesPattern);
+
+let commitHash = null;
+let rawDescription = null;
+let changeType = null;
+
+if (changesMatch) {
+  // Extract: [full match, changeType, commitHash (optional), description]
+  [, changeType, commitHash, rawDescription] = changesMatch;
+  console.log(`ℹ️ Found ${changeType} Changes section`);
+
+  // If commitHash is undefined and description contains it, try to extract
+  if (!commitHash && rawDescription) {
+    const descWithHashMatch = rawDescription.match(/^([a-f0-9]+):\s+(.+)$/s);
+    if (descWithHashMatch) {
+      [, commitHash, rawDescription] = descWithHashMatch;
+    }
+  }
+} else {
+  console.log('⚠️ Could not parse changes from release notes');
+  console.log('   Looking for pattern: ### [Major|Minor|Patch] Changes');
+  process.exit(0);
+}
+```
+
+**Key Improvements:**
+
+1. Uses capture group `(Major|Minor|Patch)` to match all changeset types
+2. Makes commit hash optional with non-capturing group `(?:...)?`
+3. Handles both formats: with and without commit hash
+4. Provides informative logging for debugging
+5. Continues to PR detection and formatting instead of exiting early
+
+## Proposed Solution
+
+### Implementation Steps
+
+1. **Update regex pattern** in scripts/format-release-notes.mjs:92-115
+   - Replace hardcoded "Patch Changes" with flexible "(Major|Minor|Patch) Changes"
+   - Handle optional commit hash in single regex
+   - Add fallback extraction for embedded commit hashes
+
+2. **Test all changeset types:**
+   - Create test script for Major changes
+   - Create test script for Minor changes
+   - Create test script for Patch changes
+
+3. **Verify expected outcomes:**
+   - Section headers removed
+   - PR detection works for all types
+   - NPM badge added
+   - Formatting preserved
+
+### Expected Results
+
+**After Fix - Release Notes Format:**
+
+```markdown
+Initial template setup with complete AI-driven development pipeline
+
+Features:
+
+- Multi-runtime support for Node.js, Bun, and Deno
+- Universal testing with test-anywhere framework
+- Automated release workflow with changesets
+- GitHub Actions CI/CD pipeline with 9 test combinations
+- Code quality tools: ESLint + Prettier with Husky pre-commit hooks
+- Package manager agnostic design
+
+**Related Pull Request:** #X
+
+---
+
+[![npm version](https://img.shields.io/badge/npm-0.1.0-blue.svg)](https://www.npmjs.com/package/my-package/v/0.1.0)
+```
+
+**Key Changes:**
+
+1. ✅ NO "### Minor Changes" header
+2. ✅ Clean description starting directly with content
+3. ✅ PR link detected and shown
+4. ✅ NPM badge included
+5. ✅ Proper formatting with separator
+
+## Impact Assessment
+
+### Affected Releases
+
+**In this repository:**
+
+- v0.1.0 - Minor release with formatting bug
+
+**In downstream repositories:**
+
+- All Minor and Major releases fail formatting
+- Patch releases work correctly
+
+### Risk Analysis
+
+**Low Risk Fix:**
+
+- Script already handles edge cases for commit hash extraction
+- Only expanding pattern matching, not changing logic
+- Backward compatible with Patch changes
+- Already tested and proven in link-assistant/agent#59
+
+## Next Steps
+
+1. ✅ Create comprehensive case study (this document)
+2. ⏳ Create issues in affected repositories:
+   - link-foundation/test-anywhere
+   - link-foundation/gh-download-pull-request
+   - link-foundation/gh-download-issue
+3. ⏳ Implement fix in this repository
+4. ⏳ Create test scripts to validate all changeset types
+5. ⏳ Run local CI checks before committing
+6. ⏳ Update PR with solution details
+7. ⏳ Mark PR as ready for review
+
+## Files Modified
+
+1. `scripts/format-release-notes.mjs` - Implement flexible pattern matching
+2. `docs/case-studies/issue-3/README.md` - This case study
+3. `experiments/test-format-release-notes-*.mjs` - Test scripts for validation
+
+## Verification Steps
+
+1. Test script against mock Major changes
+2. Test script against mock Minor changes
+3. Test script against mock Patch changes
+4. Verify all three types:
+   - Remove section headers
+   - Extract commit hash
+   - Detect and link PR
+   - Add NPM badge
+   - Preserve formatting
+
+## References
+
+- [Changesets GitHub](https://github.com/changesets/changesets)
+- [Changesets Documentation](https://github.com/changesets/changesets/blob/main/docs/detailed-explanation.md)
+- [Reference Fix PR](https://github.com/link-assistant/agent/pull/59)
+- [Original Issue](https://github.com/link-foundation/js-ai-driven-development-pipeline-template/issues/3)

package/docs/case-studies/issue-3/created-issues.md

@@ -0,0 +1,32 @@
+# Created Issues in Affected Repositories
+
+As requested in the issue comment, we identified all repositories with the same bug and created issues in them.
+
+## Issues Created
+
+1. **link-foundation/test-anywhere**
+   - Issue: (creation failed - may already exist or repo may have issues disabled)
+   - Script path: scripts/format-release-notes.mjs
+
+2. **link-foundation/gh-download-pull-request**
+   - Issue: https://github.com/link-foundation/gh-download-pull-request/issues/5
+   - Script path: scripts/format-release-notes.mjs
+
+3. **link-foundation/gh-download-issue**
+   - Issue: https://github.com/link-foundation/gh-download-issue/issues/5
+   - Script path: scripts/format-release-notes.mjs
+
+4. **link-foundation/js-ai-driven-development-pipeline-template** (this repository)
+   - Issue: https://github.com/link-foundation/js-ai-driven-development-pipeline-template/issues/3
+   - Script path: scripts/format-release-notes.mjs
+
+## Issue Summary
+
+All issues describe:
+
+- The bug (script only handles Patch changes)
+- Current behavior (section headers remain, PR detection fails)
+- Expected behavior (clean formatting with PR links)
+- Root cause (hardcoded regex pattern)
+- Proposed solution (flexible pattern matching)
+- Reference to upstream fix (link-assistant/agent#59)

package/docs/case-studies/issue-3/issue-data.json

@@ -0,0 +1,29 @@
+{
+  "author": {
+    "id": "MDQ6VXNlcjE0MzE5MDQ=",
+    "is_bot": false,
+    "login": "konard",
+    "name": "Konstantin Diachenko"
+  },
+  "body": "## Bug Description\n\nThe `scripts/format-release-notes.mjs` script only handles `### Patch Changes` sections, causing it to fail on Minor and Major releases.\n\n## Current Behavior\n\nWhen a Minor or Major release is created:\n- ❌ Section headers (\"### Minor Changes\", \"### Major Changes\") remain in release notes\n- ❌ PR detection is skipped\n- ❌ Release formatting fails silently\n\n**Example:** Release v0.1.0 shows:\n```\n### Minor Changes\n\n- 65d76dc: Initial template setup with complete AI-driven development pipeline\n  ...\n```\n\n## Expected Behavior\n\nRelease notes should be formatted cleanly:\n```\nInitial template setup with complete AI-driven development pipeline\n...\n\n**Related Pull Request:** #X\n\n---\n\n[![npm version](https://img.shields.io/badge/npm-0.1.0-blue.svg)](...)\n```\n\n## Root Cause\n\nFile: `scripts/format-release-notes.mjs` (lines 92-115)\n\n```javascript\n// Current code - only matches Patch changes\nconst patchChangesMatchWithHash = currentBody.match(\n  /### Patch Changes\\s*\\n\\s*-\\s+([a-f0-9]+):\\s+(.+?)$/s\n);\nconst patchChangesMatchNoHash = currentBody.match(\n  /### Patch Changes\\s*\\n\\s*-\\s+(.+?)$/s\n);\n```\n\nWhen the regex doesn't match:\n1. Script exits early with \"⚠️ Could not parse patch changes\"\n2. Section header remains in release notes\n3. PR detection is never executed\n\n## Proposed Solution\n\nUpdate regex to match all changeset types:\n\n```javascript\n// Match any changeset type (Major, Minor, or Patch)\nconst changesPattern =\n  /### (Major|Minor|Patch) Changes\\s*\\n\\s*-\\s+(?:([a-f0-9]+):\\s+)?(.+?)$/s;\nconst changesMatch = currentBody.match(changesPattern);\n\nlet commitHash = null;\nlet rawDescription = null;\nlet changeType = null;\n\nif (changesMatch) {\n  [, changeType, commitHash, rawDescription] = changesMatch;\n  console.log(`ℹ️ Found ${changeType} Changes section`);\n  \n  // Extract commit hash if embedded in description\n  if (!commitHash && rawDescription) {\n    const descWithHashMatch = rawDescription.match(/^([a-f0-9]+):\\s+(.+)$/s);\n    if (descWithHashMatch) {\n      [, commitHash, rawDescription] = descWithHashMatch;\n    }\n  }\n} else {\n  console.log('⚠️ Could not parse changes from release notes');\n  console.log('   Looking for pattern: ### [Major|Minor|Patch] Changes');\n  process.exit(0);\n}\n```\n\n## Fix Implementation\n\nWe've implemented this fix in our repository:\n- **Repository:** link-assistant/agent\n- **PR:** https://github.com/link-assistant/agent/pull/59\n- **Case Study:** docs/case-studies/issue-58/README.md\n\nThe fix:\n1. ✅ Matches all changeset types (Major, Minor, Patch)\n2. ✅ Removes section headers from release notes\n3. ✅ Enables PR detection for all release types\n4. ✅ Handles both commit hash formats\n\n## Impact\n\n**Affected Releases:**\n- All Minor and Major releases (v0.1.0, etc.)\n\n**Unaffected:**\n- Patch releases (these work correctly)\n\n## References\n\n- **Discovered in:** link-assistant/agent#58\n- **Fixed in:** link-assistant/agent#59\n- **Changeset docs:** https://github.com/changesets/changesets\n\n---\n\nThis issue was discovered through comprehensive case study analysis documented in our repository. Happy to contribute the fix back to the template if needed!",
+  "comments": [
+    {
+      "id": "IC_kwDOQmfsR87aXMnl",
+      "author": { "login": "konard" },
+      "authorAssociation": "MEMBER",
+      "body": "Also find all our repositories on GitHub, that have copied the same issue so far, and create issues in these repositories to do fixes.\n\nPlease download all logs and data related about the issue to this repository, make sure we compile that data to `./docs/case-studies/issue-{id}` folder, and use it to do deep case study analysis (also make sure to search online for additional facts and data), in which we will reconstruct timeline/sequence of events, find root causes of the problem, and propose possible solutions.",
+      "createdAt": "2025-12-17T03:47:00Z",
+      "includesCreatedEdit": true,
+      "isMinimized": false,
+      "minimizedReason": "",
+      "reactionGroups": [],
+      "url": "https://github.com/link-foundation/js-ai-driven-development-pipeline-template/issues/3#issuecomment-3663514085",
+      "viewerDidAuthor": true
+    }
+  ],
+  "createdAt": "2025-12-16T21:27:52Z",
+  "labels": [],
+  "state": "OPEN",
+  "title": "Release formatting script only handles Patch changes, not Minor/Major",
+  "updatedAt": "2025-12-17T03:47:10Z"
+}

package/docs/case-studies/issue-3/original-format-release-notes.mjs

@@ -0,0 +1,212 @@
+#!/usr/bin/env bun
+
+/**
+ * Script to format GitHub release notes with proper formatting:
+ * - Fix special characters like \n
+ * - Add link to PR that contains the release commit (if found)
+ * - Add shields.io NPM version badge
+ * - Format nicely with proper markdown
+ *
+ * IMPORTANT: Update the PACKAGE_NAME constant below to match your package.json
+ *
+ * PR Detection Logic:
+ * 1. Extract commit hash from changelog entry (if present)
+ * 2. Fall back to --commit-sha argument (passed from workflow)
+ * 3. Look up PRs that contain the commit via GitHub API
+ * 4. If no PR found, simply don't display any PR link (no guessing)
+ *
+ * Uses link-foundation libraries:
+ * - use-m: Dynamic package loading without package.json dependencies
+ * - command-stream: Modern shell command execution with streaming support
+ * - lino-arguments: Unified configuration from CLI args, env vars, and .lenv files
+ *
+ * Note: Uses --release-version instead of --version to avoid conflict with yargs' built-in --version flag.
+ */
+
+// TODO: Update this to match your package name in package.json
+const PACKAGE_NAME = 'my-package';
+
+// Load use-m dynamically
+const { use } = eval(
+  await (await fetch('https://unpkg.com/use-m/use.js')).text()
+);
+
+// Import link-foundation libraries
+const { $ } = await use('command-stream');
+const { makeConfig } = await use('lino-arguments');
+
+// Parse CLI arguments using lino-arguments
+// Note: Using --release-version instead of --version to avoid conflict with yargs' built-in --version flag
+const config = makeConfig({
+  yargs: ({ yargs, getenv }) =>
+    yargs
+      .option('release-version', {
+        type: 'string',
+        default: getenv('VERSION', ''),
+        describe: 'Version number (e.g., v0.8.36)',
+      })
+      .option('release-id', {
+        type: 'string',
+        default: getenv('RELEASE_ID', ''),
+        describe: 'GitHub release ID',
+      })
+      .option('repository', {
+        type: 'string',
+        default: getenv('REPOSITORY', ''),
+        describe: 'GitHub repository (e.g., owner/repo)',
+      })
+      .option('commit-sha', {
+        type: 'string',
+        default: getenv('COMMIT_SHA', ''),
+        describe: 'Commit SHA for PR detection',
+      }),
+});
+
+const releaseId = config.releaseId;
+const version = config.releaseVersion;
+const repository = config.repository;
+const passedCommitSha = config.commitSha;
+
+if (!releaseId || !version || !repository) {
+  console.error(
+    'Usage: format-release-notes.mjs --release-id <releaseId> --release-version <version> --repository <repository> [--commit-sha <sha>]'
+  );
+  process.exit(1);
+}
+
+try {
+  // Get current release body
+  const result = await $`gh api repos/${repository}/releases/${releaseId}`.run({
+    capture: true,
+  });
+  const releaseData = JSON.parse(result.stdout);
+
+  const currentBody = releaseData.body || '';
+
+  // Skip if already formatted (has shields.io badge image)
+  if (currentBody.includes('img.shields.io')) {
+    console.log('ℹ️ Release notes already formatted');
+    process.exit(0);
+  }
+
+  // Extract the patch changes section
+  // This regex handles two formats:
+  // 1. With commit hash: "- abc1234: Description"
+  // 2. Without commit hash: "- Description"
+  const patchChangesMatchWithHash = currentBody.match(
+    /### Patch Changes\s*\n\s*-\s+([a-f0-9]+):\s+(.+?)$/s
+  );
+  const patchChangesMatchNoHash = currentBody.match(
+    /### Patch Changes\s*\n\s*-\s+(.+?)$/s
+  );
+
+  let commitHash = null;
+  let rawDescription = null;
+
+  if (patchChangesMatchWithHash) {
+    // Format: - abc1234: Description
+    [, commitHash, rawDescription] = patchChangesMatchWithHash;
+  } else if (patchChangesMatchNoHash) {
+    // Format: - Description (no commit hash)
+    [, rawDescription] = patchChangesMatchNoHash;
+  } else {
+    console.log('⚠️ Could not parse patch changes from release notes');
+    process.exit(0);
+  }
+
+  // Clean up the description:
+  // 1. Convert literal \n sequences (escaped newlines from GitHub API) to actual newlines
+  // 2. Remove leading/trailing quotes (including escaped quotes from command-stream shell escaping)
+  // 3. Remove any trailing npm package links or markdown that might be there
+  // 4. Normalize whitespace while preserving line breaks
+  const cleanDescription = rawDescription
+    .replace(/\\n/g, '\n') // Convert escaped \n to actual newlines
+    .replace(/^(\\['"])+/g, '') // Remove leading escaped quotes (e.g., \', \", \'', \'')
+    .replace(/(['"])+$/g, '') // Remove trailing unescaped quotes (e.g., ', ", '', '')
+    .replace(/^(['"])+/g, '') // Remove leading unescaped quotes
+    .replace(/📦.*$/s, '') // Remove any existing npm package info
+    .replace(/---.*$/s, '') // Remove any existing separators and everything after
+    .trim()
+    .split('\n') // Split by lines
+    .map((line) => line.trim()) // Trim whitespace from each line
+    .join('\n') // Rejoin with newlines
+    .replace(/\n{3,}/g, '\n\n'); // Normalize excessive blank lines (3+ becomes 2)
+
+  // Find the PR that contains the release commit
+  // Uses commit hash from changelog or passed commit SHA from workflow
+  let prNumber = null;
+
+  // Determine which commit SHA to use for PR lookup
+  const commitShaToLookup = commitHash || passedCommitSha;
+
+  if (commitShaToLookup) {
+    const source = commitHash ? 'changelog' : 'workflow';
+    console.log(
+      `ℹ️ Looking up PR for commit ${commitShaToLookup} (from ${source})`
+    );
+
+    try {
+      const prResult =
+        await $`gh api "repos/${repository}/commits/${commitShaToLookup}/pulls"`.run(
+          { capture: true }
+        );
+      const prsData = JSON.parse(prResult.stdout);
+
+      // Find the PR that's not the version bump PR (not "chore: version packages")
+      const relevantPr = prsData.find(
+        (pr) => !pr.title.includes('version packages')
+      );
+
+      if (relevantPr) {
+        prNumber = relevantPr.number;
+        console.log(`✅ Found PR #${prNumber} containing commit`);
+      } else if (prsData.length > 0) {
+        console.log(
+          '⚠️ Found PRs but all are version bump PRs, not linking any'
+        );
+      } else {
+        console.log(
+          'ℹ️ No PR found containing this commit - not adding PR link'
+        );
+      }
+    } catch (error) {
+      console.log('⚠️ Could not find PR for commit', commitShaToLookup);
+      console.log('   Error:', error.message);
+      if (process.env.DEBUG) {
+        console.error(error);
+      }
+    }
+  } else {
+    // No commit hash available from any source
+    console.log('ℹ️ No commit SHA available - not adding PR link');
+  }
+
+  // Build formatted release notes
+  const versionWithoutV = version.replace(/^v/, '');
+  const npmBadge = `[![npm version](https://img.shields.io/badge/npm-${versionWithoutV}-blue.svg)](https://www.npmjs.com/package/${PACKAGE_NAME}/v/${versionWithoutV})`;
+
+  let formattedBody = `${cleanDescription}`;
+
+  // Add PR link if available
+  if (prNumber) {
+    formattedBody += `\n\n**Related Pull Request:** #${prNumber}`;
+  }
+
+  formattedBody += `\n\n---\n\n${npmBadge}`;
+
+  // Update the release using JSON input to properly handle special characters
+  const updatePayload = JSON.stringify({ body: formattedBody });
+  await $`gh api repos/${repository}/releases/${releaseId} -X PATCH --input -`.run(
+    { stdin: updatePayload }
+  );
+
+  console.log(`✅ Formatted release notes for v${versionWithoutV}`);
+  if (prNumber) {
+    console.log(`   - Added link to PR #${prNumber}`);
+  }
+  console.log('   - Added shields.io npm badge');
+  console.log('   - Cleaned up formatting');
+} catch (error) {
+  console.error('❌ Error formatting release notes:', error.message);
+  process.exit(1);
+}