ci(release): derive version from release tag and temporarily rewrite package.json

Update the stable release workflow to extract the version directly from the
GitHub release tag (vX.Y.Z) and temporarily rewrite package.json during CI.
This decouples the release tag source of truth from the source manifest.

Changes:
- Add inline version resolution step that parses stable vX.Y.Z format from tag
- Add temporary package.json rewrite step before verification
- Move verification to validate the rewritten manifest
- Update tests to reflect the new behavior and validate tag format
- Update README documentation for the new release flow

Co-Authored-By: Hagicode <noreply@hagicode.com>

Author: newbe36524

.github/workflows/npm-publish-dev.yml

@@ -83,11 +83,44 @@ jobs:
           cache-dependency-path: package-lock.json
           registry-url: https://registry.npmjs.org
 
-      - name: Verify release tag matches package version
+      - name: Resolve stable release version
         id: version
+        env:
+          RELEASE_TAG_NAME: ${{ github.event.release.tag_name }}
         run: |
-          version="$(npm run --silent publish:verify-release -- "${{ github.event.release.tag_name }}")"
+          version="$(node --input-type=module <<'EOF'
+          const tagName = process.env.RELEASE_TAG_NAME ?? "";
+          const match = tagName.match(/^v(?<major>0|[1-9]\d*)\.(?<minor>0|[1-9]\d*)\.(?<patch>0|[1-9]\d*)$/);
+
+          if (!match?.groups) {
+            console.error(`Release tags must use the stable vX.Y.Z format. Received: ${tagName}`);
+            process.exit(1);
+          }
+
+          process.stdout.write(`${match.groups.major}.${match.groups.minor}.${match.groups.patch}`);
+          EOF
+          )"
           echo "version=$version" >> "$GITHUB_OUTPUT"
+          echo "Resolved stable release version: $version"
+
+      - name: Temporarily rewrite package.json version for stable publish
+        env:
+          RELEASE_VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          node --input-type=module <<'EOF'
+          import fs from "node:fs";
+
+          const packageJsonPath = "package.json";
+          const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+
+          packageJson.version = process.env.RELEASE_VERSION;
+          fs.writeFileSync(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`);
+          EOF
+          echo "Temporarily rewrote package.json to version $RELEASE_VERSION"
+
+      - name: Verify release tag matches package version
+        run: |
+          version="$(npm run --silent publish:verify-release -- "${{ github.event.release.tag_name }}")"
           echo "Validated release version: $version"
 
       - name: Install dependencies

README.md

@@ -36,7 +36,7 @@ ImgBin includes a GitHub Actions based npm publishing workflow for both prerelea
 - Pushes to `main` publish a unique prerelease build to the npm `dev` dist-tag.
 - Pushes to `main` also refresh the GitHub draft release notes through Release Drafter.
 - Stable releases publish only when a GitHub draft release for tag `vX.Y.Z` is published and target the npm `latest` dist-tag.
-- The stable release workflow fails if the release tag version does not exactly match `package.json`.
+- The stable release workflow derives the publish version from the GitHub Release tag, temporarily rewrites `package.json` to that version inside CI, and then verifies the rewritten manifest before publishing.
 
 ### Release draft flow
 
@@ -73,17 +73,17 @@ npm run pack:check
 
 For a stable release:
 
-1. update `package.json` to the target stable version,
-2. make sure the Release Drafter draft uses the matching tag such as `v0.1.0`, and
+1. make sure the Release Drafter draft uses the target stable tag such as `v0.1.1`,
+2. optionally simulate the workflow locally by rewriting a temporary copy of `package.json` to `0.1.1` and running `node scripts/verify-release-version.mjs v0.1.1 /path/to/temp-package.json`, and
 3. publish that draft release from the GitHub UI.
 
-The stable publish workflow checks out the published release tag and validates that it still matches `package.json` before running `npm publish --tag latest`.
+The stable publish workflow checks out the published release tag, resolves `0.1.1` from `v0.1.1`, temporarily rewrites `package.json` to `0.1.1`, and then validates that rewritten manifest before running `npm publish --tag latest`.
 
 ### Troubleshooting release drafts
 
 - If the draft notes are empty or mis-categorized, check the merged PR labels against `repos/imgbin/.github/release-drafter.yml`.
 - If `latest` did not publish after releasing the draft, inspect `repos/imgbin/.github/workflows/npm-publish-dev.yml` for the `release.published` run.
-- If the workflow reports a version mismatch, compare the published release tag with `package.json` and rerun after correcting the version source of truth.
+- If the workflow reports a version mismatch, compare the published release tag with the temporary `package.json` rewrite step output and rerun after correcting the release tag or manifest source.
 - If you need to discard a pending stable release, delete the draft release in GitHub before publishing it.
 
 ## Usage guide

src/__tests__/release-version-script.test.ts

@@ -13,15 +13,16 @@ function writeJson(filePath: string, data: unknown) {
 }
 
 describe('verify-release-version script', () => {
-  it('accepts a GitHub release event payload as the tag source', () => {
+  it('accepts a GitHub release event payload after package.json is temporarily rewritten to the tag version', () => {
     const tempDir = mkdtempSync(path.join(os.tmpdir(), 'imgbin-release-version-'));
 
     try {
       const packageJsonPath = path.join(tempDir, 'package.json');
       const eventPath = path.join(tempDir, 'release-event.json');
 
       writeJson(packageJsonPath, { name: '@hagicode/imgbin', version: '1.2.3' });
-      writeJson(eventPath, { release: { tag_name: 'v1.2.3' } });
+      writeJson(eventPath, { release: { tag_name: 'v1.2.4' } });
+      writeJson(packageJsonPath, { name: '@hagicode/imgbin', version: '1.2.4' });
 
       const result = spawnSync(process.execPath, [scriptPath, '', packageJsonPath], {
         cwd: tempDir,
@@ -30,13 +31,13 @@ describe('verify-release-version script', () => {
       });
 
       expect(result.status).toBe(0);
-      expect(result.stdout).toBe('1.2.3');
+      expect(result.stdout).toBe('1.2.4');
     } finally {
       rmSync(tempDir, { recursive: true, force: true });
     }
   });
 
-  it('fails when the published release tag does not match package.json', () => {
+  it('fails when the temporary package.json rewrite does not align with the published release tag', () => {
     const tempDir = mkdtempSync(path.join(os.tmpdir(), 'imgbin-release-version-'));
 
     try {
@@ -58,4 +59,24 @@ describe('verify-release-version script', () => {
       rmSync(tempDir, { recursive: true, force: true });
     }
   });
+
+  it('fails when the release tag is not in the stable vX.Y.Z format', () => {
+    const tempDir = mkdtempSync(path.join(os.tmpdir(), 'imgbin-release-version-'));
+
+    try {
+      const packageJsonPath = path.join(tempDir, 'package.json');
+      writeJson(packageJsonPath, { name: '@hagicode/imgbin', version: '1.2.3' });
+
+      const result = spawnSync(process.execPath, [scriptPath, 'release-1.2.3', packageJsonPath], {
+        cwd: tempDir,
+        env: process.env,
+        encoding: 'utf8'
+      });
+
+      expect(result.status).not.toBe(0);
+      expect(result.stderr).toContain('stable vX.Y.Z format');
+    } finally {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
 });

src/__tests__/release-workflows.test.ts

@@ -50,16 +50,36 @@ describe('release workflow configuration', () => {
     const checkoutStep = releaseJob.steps.find((step: Record<string, unknown>) => step.name === 'Checkout repository');
     expect(checkoutStep.with.ref).toBe('${{ github.event.release.tag_name }}');
 
+    const resolveVersionStep = releaseJob.steps.find(
+      (step: Record<string, unknown>) => step.name === 'Resolve stable release version'
+    );
+    expect(resolveVersionStep.id).toBe('version');
+    expect(resolveVersionStep.env.RELEASE_TAG_NAME).toBe('${{ github.event.release.tag_name }}');
+    expect(resolveVersionStep.run).toContain('process.env.RELEASE_TAG_NAME');
+    expect(resolveVersionStep.run).toContain('stable vX.Y.Z format');
+
+    const rewriteVersionStep = releaseJob.steps.find(
+      (step: Record<string, unknown>) => step.name === 'Temporarily rewrite package.json version for stable publish'
+    );
+    expect(rewriteVersionStep.env.RELEASE_VERSION).toBe('${{ steps.version.outputs.version }}');
+    expect(rewriteVersionStep.run).toContain('packageJson.version = process.env.RELEASE_VERSION');
+    expect(rewriteVersionStep.run).toContain('Temporarily rewrote package.json');
+
+    const verifyStep = releaseJob.steps.find(
+      (step: Record<string, unknown>) => step.name === 'Verify release tag matches package version'
+    );
+    expect(verifyStep.run).toContain('publish:verify-release');
+    expect(verifyStep.run).toContain('${{ github.event.release.tag_name }}');
+
     const stepNames = releaseJob.steps.map((step: Record<string, unknown>) => step.name);
-    expect(stepNames).toEqual(
-      expect.arrayContaining([
-        'Verify release tag matches package version',
-        'Install dependencies',
-        'Build package',
-        'Run tests',
-        'Verify packed files',
-        'Publish to npm latest dist-tag'
-      ])
+    expect(stepNames.indexOf('Resolve stable release version')).toBeLessThan(
+      stepNames.indexOf('Temporarily rewrite package.json version for stable publish')
+    );
+    expect(stepNames.indexOf('Temporarily rewrite package.json version for stable publish')).toBeLessThan(
+      stepNames.indexOf('Verify release tag matches package version')
+    );
+    expect(stepNames.indexOf('Verify release tag matches package version')).toBeLessThan(
+      stepNames.indexOf('Install dependencies')
     );
   });
 });