shakapacker 9.6.0 → 9.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 29ddbd1208812fcd408ad972572976c01e8f0054bf77ce2a94dea8427ae5b43c
-  data.tar.gz: 8442839f7b882c54f5ab55b8fdff2ebcded5d2a162ac9afa6ff0ddac8e0405a0
+  metadata.gz: 518eb8673a021c5e18507ebc14ba593128288ddb9f735390581bd998d1f33715
+  data.tar.gz: 3c2c532321d8c79e4374fbbe0854319d6ebd89df33557e21a4ce6e4ec322cc7c
 SHA512:
-  metadata.gz: 125a9aa76ca650ae26419fcafd57030110cf580d59cd160027f9d8260aa9bad422acf5781a9276e4ac3cf63a1940948f37ca29af3cbe645cbdfa09a7395adf90
-  data.tar.gz: '0160691ce913ee23585e136a17061681e7aab3af08a39b96e97542444e311d86807de7d2385ed1d51590e7a58aef2c936c34cb342f95db15fdd0e3c18579f246'
+  metadata.gz: 26414fbf14fe2d835262ee5a6d2b46a9e50c76eee0391a0d859b60ee60f8899a87fa0e8c9d39aa651a8eadecb37639cd9684e775dd2004a55f83bb1f8aa4647e
+  data.tar.gz: 13f248afecdaa3ef579a20f7abf7ed592db788c2e5aa6b119a4940429b1e3c6f0bae263b985abe78e6ed0217116c6eeb9483c252f3a38bddd33e1c6e4533cc2c

data/.claude/commands/address-review.md

@@ -0,0 +1,206 @@
+---
+description: Fetch GitHub PR review comments, triage them, create todos for must-fix items, reply to comments, and resolve addressed threads
+---
+
+Fetch review comments from a GitHub PR in this repository, triage them, and create a todo list only for items worth addressing.
+
+# Instructions
+
+## Step 1: Determine the Repository
+
+```bash
+REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
+```
+
+If this command fails, ensure `gh` CLI is installed and authenticated (`gh auth status`).
+
+## Step 2: Parse User Input
+
+Extract the PR number and optional review/comment ID from the user's message:
+
+**Supported formats:**
+
+- PR number only: `12345`
+- PR URL: `https://github.com/org/repo/pull/12345`
+- Specific PR review: `https://github.com/org/repo/pull/12345#pullrequestreview-123456789`
+- Specific issue comment: `https://github.com/org/repo/pull/12345#issuecomment-123456789`
+
+**URL parsing:**
+
+- Extract org/repo from URL path: `github.com/{org}/{repo}/pull/{PR_NUMBER}`
+- Extract fragment ID after `#` (e.g., `pullrequestreview-123456789` → `123456789`)
+- If a full GitHub URL is provided, use the org/repo from the URL instead of the current repo
+
+## Step 3: Fetch Review Comments
+
+**If a specific issue comment ID is provided (`#issuecomment-...`):**
+
+```bash
+gh api repos/${REPO}/issues/comments/{COMMENT_ID} | jq '{body: .body, user: .user.login, html_url: .html_url}'
+```
+
+**If a specific review ID is provided (`#pullrequestreview-...`):**
+
+```bash
+gh api repos/${REPO}/pulls/{PR_NUMBER}/reviews/{REVIEW_ID}/comments | jq '[.[] | {id: .id, path: .path, body: .body, line: .line, start_line: .start_line, user: .user.login}]'
+```
+
+**If only PR number is provided (fetch all PR review comments):**
+
+```bash
+gh api repos/${REPO}/pulls/{PR_NUMBER}/comments | jq '[.[] | {id: .id, path: .path, body: .body, line: .line, start_line: .start_line, user: .user.login, in_reply_to_id: .in_reply_to_id}]'
+```
+
+**Filtering comments:**
+
+- Skip comments where `in_reply_to_id` is set (these are replies, not top-level comments)
+- Do not skip bot-generated comments by default. Many actionable review comments in this repository come from bots.
+- Deduplicate repeated bot comments and skip bot status posts, summaries, and acknowledgments that do not require a code or documentation change
+- Treat as actionable by default only: correctness bugs, regressions, missing tests, and clear inconsistencies with adjacent code
+- Treat as non-actionable by default: style nits, speculative suggestions, changelog wording, duplicate bot comments, and "could consider" feedback unless the user explicitly asks for polish work
+- Focus on actionable feedback, not acknowledgments or thank-you messages
+
+**Error handling:**
+
+- If the API returns 404, the PR/comment doesn't exist - inform the user
+- If the API returns 403, check authentication with `gh auth status`
+- If the response is empty, inform the user no review comments were found
+
+## Step 4: Triage Comments
+
+Before creating any todos, classify every review comment into one of three categories:
+
+- `MUST-FIX`: correctness bugs, regressions, security issues, missing tests that could hide a real bug, and clear inconsistencies with adjacent code that would likely block merge
+- `DISCUSS`: reasonable suggestions that expand scope, architectural opinions that are not clearly right or wrong, and comments where the reviewer claim may be correct but needs a user decision
+- `SKIPPED`: style preferences, documentation nits, comment requests, test-shape preferences, speculative suggestions, changelog wording, duplicate comments, status posts, summaries, and factually incorrect suggestions
+
+Triage rules:
+
+- Deduplicate overlapping comments before classifying them. Keep one representative item for the underlying issue.
+- Verify factual claims locally before classifying a comment as `MUST-FIX`.
+- If a claim appears wrong, classify it as `SKIPPED` and note briefly why.
+- Preserve the original review comment ID and thread ID when available so the command can reply to the correct place and resolve the correct thread later.
+
+## Step 5: Create Todo List
+
+Create a todo list with TodoWrite containing **only the `MUST-FIX` items**:
+
+- One todo per must-fix comment or deduplicated issue
+- For file-specific comments: `"{file}:{line} - {comment_summary} (@{username})"` (content)
+- For general comments: Parse the comment body and extract the must-fix action
+- Format activeForm: `"Addressing {brief description}"`
+- All todos should start with status: `"pending"`
+
+## Step 6: Present Triage to User
+
+Present the triage to the user - **DO NOT automatically start addressing items**:
+
+- `MUST-FIX ({count})`: list the todos created
+- `DISCUSS ({count})`: list items needing user choice, with a short reason
+- `SKIPPED ({count})`: list skipped comments with a short reason, including duplicates and factually incorrect suggestions
+- Wait for the user to tell you which items to address
+- Always offer an explicit optional follow-up to post rationale replies on selected `SKIPPED` or declined `DISCUSS` items
+- Never post those rationale replies unless the user explicitly selects which items to reply to
+- Ask two things when relevant:
+  - Which items to address in code/tests/docs
+  - Which skipped/declined items (if any) should receive a rationale reply
+
+## Step 7: Address Items, Reply, and Resolve
+
+When addressing items, after completing each selected todo item, reply to the original review comment explaining how it was addressed.
+If the user selects skipped/declined items for rationale replies, post those replies too.
+
+**For issue comments (general PR comments):**
+
+```bash
+gh api repos/${REPO}/issues/{PR_NUMBER}/comments -X POST -f body="<response>"
+```
+
+**For PR review comments (file-specific, replying to a thread):**
+
+```bash
+gh api repos/${REPO}/pulls/{PR_NUMBER}/comments/{COMMENT_ID}/replies -X POST -f body="<response>"
+```
+
+**For standalone review comments (not in a thread):**
+
+```bash
+gh api repos/${REPO}/pulls/{PR_NUMBER}/comments -X POST -f body="<response>" -f commit_id="<COMMIT_SHA>" -f path="<FILE_PATH>" -f line=<LINE_NUMBER> -f side="RIGHT"
+```
+
+Note: `side` is required when using `line`. Use `"RIGHT"` for the PR commit side (most common) or `"LEFT"` for the base commit side.
+
+The response should briefly explain:
+
+- What was changed
+- Which commit(s) contain the fix
+- Any relevant details or decisions made
+
+After posting the reply, resolve the review thread when all of the following are true:
+
+- The comment belongs to a review thread and you have the thread ID
+- The concern was actually addressed in code, tests, or documentation, or it was explicitly declined with a clear explanation approved by the user
+- The thread is not already resolved
+
+Use GitHub GraphQL to resolve the thread:
+
+```bash
+gh api graphql -f query='mutation($threadId:ID!) { resolveReviewThread(input:{threadId:$threadId}) { thread { id isResolved } } }' -f threadId="<THREAD_ID>"
+```
+
+Do not resolve a thread if the fix is still pending, if you are unsure whether the reviewer concern is satisfied, or if the user asked to leave the thread open.
+
+If the user explicitly asks to close out a `DISCUSS` or `SKIPPED` item, reply with the rationale and resolve the thread only when the conversation is actually complete.
+
+# Example Usage
+
+```text
+/address-review https://github.com/org/repo/pull/12345#pullrequestreview-123456789
+/address-review https://github.com/org/repo/pull/12345#issuecomment-123456789
+/address-review 12345
+/address-review https://github.com/org/repo/pull/12345
+```
+
+# Example Output
+
+After fetching and triaging comments, present them like this:
+
+```text
+Found 5 review comments. Triage:
+
+MUST-FIX (1):
+1. ⬜ src/helper.rb:45 - Missing nil guard causes a crash on empty input (@reviewer1)
+
+DISCUSS (1):
+2. src/config.rb:12 - Extract this to a shared config constant (@reviewer1)
+   Reason: reasonable suggestion, but it expands scope
+
+SKIPPED (3):
+3. src/helper.rb:50 - "Consider adding a comment" (@claude[bot]) - documentation nit
+4. src/helper.rb:45 - Same nil guard issue (@greptile-apps[bot]) - duplicate of #1
+5. spec/helper_spec.rb:20 - "Consolidate assertions" (@claude[bot]) - test style preference
+
+Which items would you like me to address? (e.g., "1", "1,2", or "all must-fix")
+Optional: I can also post rationale replies for skipped/declined items (e.g., "reply 3,5" or "reply all skipped").
+```
+
+# Important Notes
+
+- Automatically detect the repository using `gh repo view` for the current working directory
+- If a GitHub URL is provided, extract the org/repo from the URL
+- Include file path and line number in each todo for easy navigation (when available)
+- Include the reviewer's username in the todo text
+- If a comment doesn't have a specific line number, note it as "general comment"
+- **NEVER automatically address all review comments** - always wait for user direction
+- When given a specific review URL, no need to ask for more information
+- **ALWAYS reply to comments after addressing them** to close the feedback loop
+- After triage, always offer to post rationale replies for selected `SKIPPED`/declined items, but only post them with explicit user approval
+- Resolve the review thread after replying when the concern is actually addressed and a thread ID is available
+- Default to real issues only. Do not spend a review cycle on optional polish unless the user explicitly asks for it
+- Triage comments before creating todos. Only `MUST-FIX` items should become todos by default
+- For large review comments (like detailed code reviews), parse and extract the actionable items into separate todos
+
+# Known Limitations
+
+- Rate limiting: GitHub API has rate limits; if you hit them, wait a few minutes
+- Private repos: Requires appropriate `gh` authentication scope

data/.claude/commands/update-changelog.md

@@ -7,9 +7,10 @@ You are helping to add an entry to the CHANGELOG.md file for the Shakapacker pro
 This command accepts an optional argument: `$ARGUMENTS`
 
 - **No argument** (`/update-changelog`): Add entries to `[Unreleased]` without stamping a version header. Use this during development.
-- **`release`** (`/update-changelog release`): Add entries and stamp a version header. Auto-compute the next version based on changes (breaking → major, added features → minor, fixes → patch). Then `rake create_release` (with no args) will pick up this version automatically.
+- **`release`** (`/update-changelog release`): Add entries and stamp a version header. Auto-compute the next version based on changes (breaking → major, added features → minor, fixes → patch). Then `rake release` (with no args) will pick up this version automatically.
 - **`rc`** (`/update-changelog rc`): Same as `release`, but stamps an RC prerelease version (e.g., `v9.7.0-rc.0`). Auto-increments the RC index if prior RCs exist for the same base version.
 - **`beta`** (`/update-changelog beta`): Same as `rc`, but stamps a beta prerelease version (e.g., `v9.7.0-beta.0`).
+- **Explicit version** (`/update-changelog 9.7.0-rc.10` or `/update-changelog v9.7.0-rc.10`): Add entries and stamp the exact version provided. Skips auto-computation — use this when you already know the target version. The version string must use npm semver format with optional `-rc.N` or `-beta.N` suffix (e.g., `9.7.0-rc.10`, `9.7.0`). A `v` prefix is optional and will be added automatically if missing. If passed in RubyGems dot format (e.g., `9.7.0.rc.10` or `9.7.0.beta.2`), convert to npm semver dash format (`v9.7.0-rc.10` or `v9.7.0-beta.2`) for the changelog header.
 
 ## When to Use This
 
@@ -25,7 +26,7 @@ This command serves three use cases at different points in the release lifecycle
 - Run `/update-changelog release` (or `rc` or `beta`) to add entries AND stamp the version header
 - The version is auto-computed from changelog content (see "Auto-Computing the Next Version" below)
 - Commit and push CHANGELOG.md
-- Then run `rake create_release` (no args needed — it reads the version from CHANGELOG.md)
+- Then run `rake release` (no args needed — it reads the version from CHANGELOG.md)
 - The release task automatically creates a GitHub release from the changelog section
 
 **After a release you forgot to update the changelog for** — Catch-up mode:
@@ -35,7 +36,7 @@ This command serves three use cases at different points in the release lifecycle
 
 ### Why changelog comes BEFORE the release
 
-- `create_release` automatically creates a GitHub release if a changelog section exists — no separate `sync_github_release` step needed
+- `release` automatically creates a GitHub release if a changelog section exists — no separate `sync_github_release` step needed
 - The release task warns if no changelog section is found for the target version
 - A premature version header (if release fails) is harmless — you'll release eventually
 - A missing changelog after release means GitHub release must be created manually
@@ -57,12 +58,12 @@ When stamping a version header (`release`, `rc`, or `beta`), compute the next ve
 
 3. **Compute the version**:
    - For `release`: Apply the bump to the latest stable tag (e.g., `9.5.0` + minor → `9.6.0`)
-   - For `rc`: Apply the bump, then find the next RC index (e.g., if `v9.6.0-rc.0` tag exists → `v9.6.0-rc.1`)
+   - For `rc`: Apply the bump, then find the next RC index based **only on git tags** (e.g., if `v9.6.0-rc.0` tag exists → `v9.6.0-rc.1`). **Do NOT use changelog headers** to determine the next index — a version header in the changelog is a draft that may not have been released yet. Only git tags represent shipped versions.
    - For `beta`: Same as RC but with beta suffix
 
 4. **Verify**: Check that the computed version is newer than ALL existing tags (stable and prerelease). If not, ask the user what to do.
 
-5. **Show the computed version to the user** and ask for confirmation before stamping the header.
+5. **Show the computed version to the user and ask for confirmation** before stamping the header. If the bump type is ambiguous (e.g., changes could reasonably be classified as patch vs minor, or the changelog headings don't clearly signal the bump level), explain your reasoning for the suggested bump and ask the user to confirm or override before proceeding.
 
 ## Critical Requirements
 
@@ -168,6 +169,8 @@ This will:
 
 After adding an entry to the `## [Unreleased]` section, ensure the version diff links at the bottom of the file are correct.
 
+**IMPORTANT**: Compare links at the bottom MUST use the `v` prefix to match git tags (e.g., `.../compare/v9.2.0...v9.3.0`). This is consistent with Shakapacker's changelog headers which also include the `v` prefix (e.g., `## [v9.3.0]`).
+
 The format at the bottom should be:
 
 ```markdown
@@ -186,59 +189,89 @@ When a new version is released:
 
 ### For Regular Changelog Updates
 
-1. **ALWAYS fetch latest changes first**:
-   - **CRITICAL**: Run `git fetch origin main --tags` to ensure you have the latest commits AND tags
-   - The workspace may be behind origin/main, causing you to miss recently merged PRs
-   - After fetching, use `origin/main` for all comparisons, NOT local `main` branch
-
-2. **Determine the correct version tag to compare against**:
-   - List all version tags sorted by semver: `git tag -l 'v*' --sort=-v:refname | head -10`
-   - This correctly sorts RC/beta tags (e.g., `v9.6.0-rc.1` sorts after `v9.6.0-rc.0` and before `v9.6.0`)
-   - The latest tag may be a stable release, RC, or beta — handle all cases
-   - Compare origin/main branch date to the tag date using: `git log -1 --format="%ai" origin/main` and `git log -1 --format="%ai" <tag>`
-   - If the tag is NEWER than origin/main, the branch needs updating to include the tag's commits
-   - **CRITICAL**: Always use `git log TAG..BRANCH` to find commits in the branch but not the tag, AND `git log BRANCH..TAG` to check if the tag is ahead
-
-3. **Check commits and version boundaries**:
-   - **IMPORTANT**: Use `origin/main` in all commands below, not local `main`
-   - Run `git log --oneline LAST_TAG..origin/main` to see commits since the last release
-   - Also check `git log --oneline origin/main..LAST_TAG` to see if the tag is ahead of origin/main
-   - If the tag is ahead, entries in "Unreleased" section may actually belong to that tagged version
-   - **Extract ALL PR numbers** from commit messages using grep: `git log --oneline LAST_TAG..origin/main | grep -oE "#[0-9]+" | sort -u`
-   - For each PR number found, check if it's already in CHANGELOG.md using: `grep "PR #XXX" CHANGELOG.md`
-   - Identify which commits contain user-visible changes (look for keywords like "Fix", "Add", "Feature", "Bug", etc.)
-   - Extract author information from commit messages
-   - **Never ask the user for PR details** - get them from the git history or use WebFetch on the PR URL
-
-4. **Validate** that changes are user-visible (per the criteria above). If not user-visible, skip those commits.
-
-5. **Read the current CHANGELOG.md** to understand the existing structure and formatting.
-
-6. **Determine where entries should go**:
-   - If the latest version tag is NEWER than origin/main branch, move entries from "Unreleased" to that version section
-   - If origin/main is ahead of the latest tag, add new entries to "Unreleased"
-   - Always verify the version date in CHANGELOG.md matches the actual tag date
-
-7. **Add or move entries** to the appropriate section under appropriate category headings.
-   - **CRITICAL**: When moving entries from "Unreleased" to a version section, merge them with existing entries under the same category heading
-   - **NEVER create duplicate section headings** (e.g., don't create two "### Fixed" sections)
-   - If the version section already has a category heading (e.g., "### Fixed"), add the moved entries to that existing section
-   - Maintain the category order as defined above
-
-8. **Verify formatting**:
+#### Step 1: Fetch and read current state
+
+- **CRITICAL**: Run `git fetch origin main --tags` to ensure you have the latest commits AND tags
+- The workspace may be behind origin/main, causing you to miss recently merged PRs
+- After fetching, use `origin/main` for all comparisons, NOT local `main` branch
+- Read the current CHANGELOG.md to understand the existing structure
+
+#### Step 2: Reconcile tags with changelog sections (DO THIS FIRST)
+
+**This step catches missing version sections and is the #1 source of errors when skipped.**
+
+1. Get the latest git tag: `git tag -l 'v*' --sort=-v:refname | head -5`
+2. Get the most recent version header in CHANGELOG.md (the first `## [vVERSION]` after `## [Unreleased]`)
+3. **Compare them.** If the latest git tag does NOT appear anywhere in the changelog version headers, there are tagged releases missing from the changelog. **Important**: Don't just compare against the _top_ changelog header — a version header may exist _above_ the latest tag if it was stamped as a draft before tagging. Check whether the tag's version appears in _any_ `## [vX.Y.Z]` header. For example:
+   - Latest tag: `v9.6.0-rc.4`, and no `## [v9.6.0-rc.4]` header exists anywhere in CHANGELOG.md
+   - **Result: `v9.6.0-rc.4` is missing and needs its own section**
+   - But if `## [v9.7.0-rc.0]` is the top header (a draft, not yet tagged) and `## [v9.6.0-rc.4]` exists below it, then nothing is missing — the top header is simply a pre-release draft
+
+4. For EACH missing tagged version (there may be multiple):
+   a. Find commits in that tag vs the previous tag: `git log --oneline PREV_TAG..MISSING_TAG`
+   b. Extract PR numbers and fetch details for user-visible changes
+   c. Check which entries currently in `## [Unreleased]` actually belong to this tagged version (compare PR numbers against the commit list)
+   d. **Create a new version section** immediately before the previous version section
+   e. **Move** matching entries from Unreleased into the new section
+   f. **Add** any new entries for PRs in that tag that aren't in the changelog at all
+   g. **Update version diff links** at the bottom of the file
+
+5. Get the tag date with: `git log -1 --format="%Y-%m-%d" TAG_NAME`
+
+#### Step 3: Add new entries for post-tag commits
+
+1. Run `git log --oneline LATEST_TAG..origin/main` to find commits after the latest tag (LATEST_TAG is the most recent git tag, i.e., the same one identified in Step 2)
+2. **Extract ALL PR numbers** from commit messages: `git log --oneline LATEST_TAG..origin/main | grep -oE "#[0-9]+" | sort -u`
+3. If Step 2 found no missing tagged versions, verify no tag is ahead of main: `git log --oneline origin/main..LATEST_TAG` should be empty. If not, entries in "Unreleased" may belong to that tagged version — Step 2 should have caught this, so re-check.
+4. For each PR number, check if it's already in CHANGELOG.md: `grep "PR #XXX" CHANGELOG.md`
+5. For PRs not yet in the changelog:
+   - Get PR details: `gh pr view NUMBER --json title,body,author --repo shakacode/shakapacker`
+   - **Never ask the user for PR details** — get them from git history or the GitHub API
+   - Validate that the change is user-visible (per the criteria above). Skip CI, lint, refactoring, test-only changes.
+   - Add the entry to `## [Unreleased]` under the appropriate category heading
+
+#### Step 4: Stamp version header (only when a version mode or explicit version is given)
+
+If the user passed `release`, `rc`, `beta`, or an explicit version string as an argument:
+
+1. Auto-compute the next version (see "Auto-Computing the Next Version" above), or use the explicit version provided
+2. Insert the version header immediately after `## [Unreleased]`
+3. For `rc`/`beta` or an explicit prerelease version (e.g., `9.7.0-rc.10`): collapse prior prerelease sections of the same base version into the new section
+4. Update version diff links at the bottom of the file
+5. **Verify** the computed version looks correct
+
+If no argument was passed, skip this step — entries stay in `## [Unreleased]`.
+
+#### Step 5: Verify and finalize
+
+1. **Verify formatting**:
    - Bold description with period
-   - Proper PR link
+   - Proper PR link (with `#` prefix for Shakapacker)
    - Proper author link
    - Consistent with existing entries
    - File ends with a newline character
-
-9. **Run linting** after making changes:
+   - **No duplicate section headings** (e.g., don't create two `### Fixed` sections — merge entries into the existing heading)
+2. **Verify version sections are in order** (Unreleased → newest tag → older tags)
+3. **Verify version diff links** at the bottom of the file are correct (compare links MUST use the `v` prefix to match git tags)
+4. **Run linting** after making changes:
 
    ```bash
    yarn lint
    ```
 
-10. **Show the user** the added or moved entries and explain what was done.
+5. **Show the user** a summary of what was done:
+   - Which version sections were created
+   - Which entries were moved from Unreleased
+   - Which new entries were added
+   - Which PRs were skipped (and why)
+6. If in `release`/`rc`/`beta` mode or explicit-version mode, **automatically commit, push, and open a PR**:
+   - Verify the working tree only has `CHANGELOG.md` changes; if there are other uncommitted changes, warn the user and stop
+   - Verify the current branch is `main` (`git branch --show-current`); if not, warn the user and stop
+   - Create a feature branch (e.g., `changelog-v9.6.0-rc.1`)
+   - Stage only `CHANGELOG.md` (`git add CHANGELOG.md`) and commit with message `Update CHANGELOG.md for vX.Y.Z` (using the stamped version)
+   - Push and open a PR with the changelog diff as the body
+   - If the push or PR creation fails, the CHANGELOG is already stamped locally — fix the issue and retry manually
+   - Remind the user to run `bundle exec rake release` (no args) after merge to publish and auto-create the GitHub release
 
 ### For Prerelease Versions (RC and Beta)
 
@@ -259,10 +292,14 @@ When the user passes `rc` or `beta` as an argument (or when creating a prereleas
 4. **Always collapse prior prereleases into the current prerelease** (this is the default behavior):
    - Combine all prior prerelease changelog entries into the new prerelease version section
    - Remove previous prerelease version sections (e.g., remove `## [v9.6.0-rc.0]` when creating `## [v9.6.0-rc.1]`)
+   - When collapsing, **consolidate duplicate category headings** — if both the Unreleased section and a prior prerelease section have `### Fixed`, merge all entries under a single `### Fixed` heading
+   - **Remove orphaned version diff links** at the bottom of the file for collapsed prerelease sections
    - Add any new user-visible changes from commits since the last prerelease
    - Update version diff links to point from the last stable version to the new prerelease
    - This keeps the changelog clean with a single prerelease section that accumulates all changes since the last stable release
 
+**Note**: The new version header must be inserted **immediately after `## [Unreleased]`** (see Step 4). This ensures correct ordering of version headers.
+
 ### For Prerelease to Stable Version Release
 
 When releasing from prerelease to a stable version (e.g., v9.6.0-rc.1 → v9.6.0):

data/.github/workflows/claude-code-review.yml

@@ -16,7 +16,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v4
         with:
           fetch-depth: 1
 

data/CHANGELOG.md

@@ -9,6 +9,27 @@
 
 ## [Unreleased]
 
+## [v9.7.0] - March 15, 2026
+
+### Added
+
+- **Added rspack v2 support**. [PR #975](https://github.com/shakacode/shakapacker/pull/975) by [justin808](https://github.com/justin808). Peer dependencies now accept both rspack v1 and v2 (`^1.0.0 || ^2.0.0-0`). No source code changes were needed — all existing APIs work identically in v2. Note that rspack v2 requires Node.js 20.19.0+.
+
+### Fixed
+
+- **Fixed config exporter path traversal and annotation format validation**. [PR #914](https://github.com/shakacode/shakapacker/pull/914) by [justin808](https://github.com/justin808). Added `safeResolvePath` security check to prevent path traversal in export save paths, and enforced YAML format when using annotations with build exports.
+- **Fixed `webpack-subresource-integrity` v5 named export handling**. [PR #978](https://github.com/shakacode/shakapacker/pull/978) by [justin808](https://github.com/justin808). Supports both the default export (older versions) and the named `SubresourceIntegrityPlugin` export (v5.1+), preventing runtime breakage when upgrading the plugin. Fixes [#972](https://github.com/shakacode/shakapacker/issues/972).
+
+## [v9.6.1] - March 8, 2026
+
+### Fixed
+
+- **Fixed `Env#current` crashing when Rails is not loaded**. [PR #963](https://github.com/shakacode/shakapacker/pull/963) by [ihabadham](https://github.com/ihabadham). Added `defined?(Rails)` guard to `Shakapacker::Env#current` so it falls back to `RAILS_ENV`/`RACK_ENV` environment variables when called from non-Rails Ruby processes (e.g., `bin/dev` scripts). Previously, this would raise a `NameError` and silently fall back to `"production"`.
+
+### Documentation
+
+- **Added Node package API documentation**. [PR #900](https://github.com/shakacode/shakapacker/pull/900) by [justin808](https://github.com/justin808). New guide (`docs/node_package_api.md`) documenting the JavaScript API exports, configuration objects, import entrypoints for webpack and rspack, and built-in third-party support resources.
+
 ## [v9.6.0] - March 7, 2026
 
 ### Security
@@ -866,7 +887,9 @@ Note: [Rubygem is 6.3.0.pre.rc.1](https://rubygems.org/gems/shakapacker/versions
 
 See [CHANGELOG.md in rails/webpacker (up to v5.4.3)](https://github.com/rails/webpacker/blob/master/CHANGELOG.md)
 
-[Unreleased]: https://github.com/shakacode/shakapacker/compare/v9.6.0...main
+[Unreleased]: https://github.com/shakacode/shakapacker/compare/v9.7.0...main
+[v9.7.0]: https://github.com/shakacode/shakapacker/compare/v9.6.1...v9.7.0
+[v9.6.1]: https://github.com/shakacode/shakapacker/compare/v9.6.0...v9.6.1
 [v9.6.0]: https://github.com/shakacode/shakapacker/compare/v9.5.0...v9.6.0
 [v9.5.0]: https://github.com/shakacode/shakapacker/compare/v9.4.0...v9.5.0
 [v9.4.0]: https://github.com/shakacode/shakapacker/compare/v9.3.4...v9.4.0

data/README.md

@@ -317,6 +317,8 @@ At its core, Shakapacker's essential function is to:
 
 **📖 For a comprehensive guide to all configuration options, see the [Configuration Guide](./docs/configuration.md)**
 
+**📦 For Node package exports and config object docs, see the [Node Package API Guide](./docs/node_package_api.md)**
+
 This includes documentation for:
 
 - All `config/shakapacker.yml` options (including `assets_bundler_config_path`)

data/Rakefile

@@ -2,6 +2,11 @@
 require "bundler/gem_tasks"
 require "pathname"
 
+# Remove Bundler's default `release` task — it bypasses the custom release flow
+# (CHANGELOG version detection, npm publish, GitHub release sync, etc.).
+# The custom `release` task in rakelib/release.rake replaces it.
+Rake::Task[:release].clear
+
 desc "Run all specs"
 task test: ["run_spec:all_specs"]
 

data/docs/node_package_api.md

@@ -0,0 +1,70 @@
+# Node Package API
+
+Shakapacker ships a Node package that exposes configuration and helper utilities
+for both webpack and rspack.
+
+## Import Paths
+
+```js
+// Webpack entrypoint
+const shakapacker = require("shakapacker")
+
+// Rspack entrypoint
+const rspack = require("shakapacker/rspack")
+```
+
+## Webpack Exports (`shakapacker`)
+
+| Export                                                    | Type      | Description                                                  |
+| --------------------------------------------------------- | --------- | ------------------------------------------------------------ |
+| `config`                                                  | object    | Parsed `config/shakapacker.yml` plus computed fields         |
+| `devServer`                                               | object    | Dev server configuration                                     |
+| `generateWebpackConfig(extraConfig?)`                     | function  | Generates final webpack config and merges optional overrides |
+| `baseConfig`                                              | object    | Base config object from `package/environments/base`          |
+| `env`                                                     | object    | Environment metadata (`railsEnv`, `nodeEnv`, booleans)       |
+| `rules`                                                   | array     | Loader rules for current bundler                             |
+| `moduleExists(name)`                                      | function  | Returns whether module can be resolved                       |
+| `canProcess(rule, fn)`                                    | function  | Runs callback only if loader dependency is available         |
+| `inliningCss`                                             | boolean   | Whether CSS should be inlined in current dev-server mode     |
+| `merge`, `mergeWithCustomize`, `mergeWithRules`, `unique` | functions | Re-exported from `webpack-merge`                             |
+
+## Rspack Exports (`shakapacker/rspack`)
+
+| Export                                                    | Type      | Description                                                 |
+| --------------------------------------------------------- | --------- | ----------------------------------------------------------- |
+| `config`                                                  | object    | Parsed `config/shakapacker.yml` plus computed fields        |
+| `devServer`                                               | object    | Dev server configuration                                    |
+| `generateRspackConfig(extraConfig?)`                      | function  | Generates final rspack config and merges optional overrides |
+| `baseConfig`                                              | object    | Base config object                                          |
+| `env`                                                     | object    | Environment metadata (`railsEnv`, `nodeEnv`, booleans)      |
+| `rules`                                                   | array     | Rspack loader rules                                         |
+| `moduleExists(name)`                                      | function  | Returns whether module can be resolved                      |
+| `canProcess(rule, fn)`                                    | function  | Runs callback only if loader dependency is available        |
+| `inliningCss`                                             | boolean   | Whether CSS should be inlined in current dev-server mode    |
+| `merge`, `mergeWithCustomize`, `mergeWithRules`, `unique` | functions | Re-exported from `webpack-merge`                            |
+
+## `config` Object
+
+`config` includes:
+
+- Raw values from `config/shakapacker.yml` (`source_path`, `public_output_path`, `javascript_transpiler`, etc.)
+- Computed absolute paths (`outputPath`, `publicPath`, `manifestPath`, `publicPathWithoutCDN`)
+- Optional sections like `dev_server` and `integrity`
+
+For the full key list and types, see:
+
+- [`package/types.ts`](../package/types.ts)
+- [Configuration Guide](./configuration.md)
+
+## Built-in Third-Party Support
+
+Installer defaults include support for:
+
+- Bundlers: webpack, rspack
+- JavaScript transpilers: SWC (default), Babel, esbuild
+- Common style/tooling loaders: css, sass, less, stylus, file/raw rules
+- Common optimization/plugins for webpack/rspack production builds
+
+Dependency presets used by the installer are defined in:
+
+- [`lib/install/package.json`](../lib/install/package.json)