periapsis 1.0.4 → 1.0.5

package/.github/workflows/prepare-package-release.yml

@@ -0,0 +1,168 @@
+name: Prepare Package Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      release_type:
+        description: Semver increment to prepare
+        required: true
+        type: choice
+        default: patch
+        options:
+          - patch
+          - minor
+          - major
+
+permissions:
+  contents: read
+
+concurrency:
+  group: prepare-package-release
+  cancel-in-progress: false
+
+jobs:
+  authorize-release:
+    name: Authorize Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require main branch
+        run: |
+          if [ "${GITHUB_REF_NAME}" != "main" ]; then
+            echo "Manual release preparation is only allowed from main."
+            exit 1
+          fi
+
+      - name: Require repository admin permission
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+            const actor = context.actor;
+
+            if (owner.toLowerCase() === actor.toLowerCase()) {
+              core.info(`Actor ${actor} matches the repository owner and is treated as admin.`);
+              return;
+            }
+
+            const response = await github.rest.repos.getCollaboratorPermissionLevel({
+              owner,
+              repo,
+              username: actor,
+            });
+
+            const { permission, role_name: roleName } = response.data;
+            core.info(`Actor ${actor} permission=${permission}, role_name=${roleName}`);
+
+            if (permission !== "admin" && roleName !== "admin") {
+              core.setFailed(`Only repository admins can prepare package releases. ${actor} has ${roleName || permission}.`);
+            }
+
+  prepare-release:
+    name: Prepare Release Pull Request
+    needs: authorize-release
+    runs-on: ubuntu-latest
+    permissions:
+      # Required because this workflow pushes a release branch and opens a PR.
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run automated test suite
+        run: npm run test:ci
+
+      - name: Bump package version
+        run: npm version "${{ inputs.release_type }}" --no-git-tag-version
+
+      - name: Read new version
+        id: version
+        run: |
+          VERSION="$(node -e 'process.stdout.write(require("./package.json").version)')"
+          echo "value=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "branch=release/v${VERSION}" >> "$GITHUB_OUTPUT"
+
+      - name: Ensure release branch is not already open
+        env:
+          RELEASE_BRANCH: ${{ steps.version.outputs.branch }}
+        run: |
+          if git ls-remote --exit-code --heads origin "${RELEASE_BRANCH}" >/dev/null 2>&1; then
+            echo "Release branch ${RELEASE_BRANCH} already exists on origin."
+            exit 1
+          fi
+
+      - name: Create release branch
+        env:
+          RELEASE_BRANCH: ${{ steps.version.outputs.branch }}
+        run: git switch -c "${RELEASE_BRANCH}"
+
+      - name: Configure git author
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Commit release version
+        env:
+          VERSION: ${{ steps.version.outputs.value }}
+        run: |
+          git add package.json package-lock.json
+          git commit -m "chore(release): v${VERSION}"
+
+      - name: Push release branch
+        env:
+          RELEASE_BRANCH: ${{ steps.version.outputs.branch }}
+        run: git push --set-upstream origin "${RELEASE_BRANCH}"
+
+      - name: Open release pull request
+        id: pull-request
+        uses: actions/github-script@v7
+        env:
+          RELEASE_BRANCH: ${{ steps.version.outputs.branch }}
+          VERSION: ${{ steps.version.outputs.value }}
+        with:
+          script: |
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+            const head = process.env.RELEASE_BRANCH;
+            const version = process.env.VERSION;
+
+            const pr = await github.rest.pulls.create({
+              owner,
+              repo,
+              title: `chore(release): v${version}`,
+              head,
+              base: "main",
+              body: [
+                `Prepares \`v${version}\` for npm publication.`,
+                "",
+                "After this pull request merges into `main`, the publish workflow will release the package to npm.",
+              ].join("\n"),
+            });
+
+            core.setOutput("url", pr.data.html_url);
+
+      - name: Write job summary
+        env:
+          VERSION: ${{ steps.version.outputs.value }}
+          RELEASE_BRANCH: ${{ steps.version.outputs.branch }}
+          PR_URL: ${{ steps.pull-request.outputs.url }}
+        run: |
+          {
+            echo "## Release PR created"
+            echo
+            echo "- Version: \`${VERSION}\`"
+            echo "- Release branch: \`${RELEASE_BRANCH}\`"
+            echo "- Pull request: ${PR_URL}"
+          } >> "$GITHUB_STEP_SUMMARY"

package/.github/workflows/publish-package.yml

@@ -1,86 +1,75 @@
 name: Publish Package
 
 on:
+  push:
+    branches:
+      - main
+    paths:
+      - package.json
+      - package-lock.json
   workflow_dispatch:
-    inputs:
-      release_type:
-        description: Semver increment to publish
-        required: true
-        type: choice
-        default: patch
-        options:
-          - patch
-          - minor
-          - major
 
 permissions:
-  contents: read
+  contents: write
+  id-token: write
 
 concurrency:
   group: publish-package
   cancel-in-progress: false
 
 jobs:
-  authorize-release:
-    name: Authorize Release
-    runs-on: ubuntu-latest
-    steps:
-      - name: Require default branch
-        env:
-          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
-        run: |
-          if [ "${GITHUB_REF_NAME}" != "${DEFAULT_BRANCH}" ]; then
-            echo "Manual publishing is only allowed from ${DEFAULT_BRANCH}."
-            exit 1
-          fi
-
-      - name: Require repository admin permission
-        uses: actions/github-script@v7
-        with:
-          script: |
-            const owner = context.repo.owner;
-            const repo = context.repo.repo;
-            const actor = context.actor;
-
-            if (owner.toLowerCase() === actor.toLowerCase()) {
-              core.info(`Actor ${actor} matches the repository owner and is treated as admin.`);
-              return;
-            }
-
-            const response = await github.rest.repos.getCollaboratorPermissionLevel({
-              owner,
-              repo,
-              username: actor,
-            });
-
-            const { permission, role_name: roleName } = response.data;
-            core.info(`Actor ${actor} permission=${permission}, role_name=${roleName}`);
-
-            if (permission !== "admin" && roleName !== "admin") {
-              core.setFailed(`Only repository admins can publish packages. ${actor} has ${roleName || permission}.`);
-            }
-
   publish-package:
     name: Publish Package
-    needs: authorize-release
     runs-on: ubuntu-latest
     environment:
-      # Configure this environment in GitHub with required reviewers for an
-      # extra approval gate, and use the same name in npm trusted publisher
-      # settings if you want npm to bind publishing to this environment.
+      # Use the same environment name in npm trusted publisher settings if you
+      # want npm to bind publishing to this protected environment.
       name: package-publish
-    permissions:
-      # Required because this workflow commits the bumped version, creates a
-      # release tag, and pushes both back to the repository.
-      contents: write
-      id-token: write
     steps:
       - name: Checkout
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
+      - name: Detect release version
+        id: release
+        env:
+          BEFORE_SHA: ${{ github.event.before }}
+          EVENT_NAME: ${{ github.event_name }}
+          REF_NAME: ${{ github.ref_name }}
+        run: |
+          VERSION="$(node -e 'process.stdout.write(require("./package.json").version)')"
+          PACKAGE_NAME="$(node -e 'process.stdout.write(require("./package.json").name)')"
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "package_name=${PACKAGE_NAME}" >> "$GITHUB_OUTPUT"
+
+          if [ "${EVENT_NAME}" = "workflow_dispatch" ]; then
+            if [ "${REF_NAME}" != "main" ]; then
+              echo "Manual publishing is only allowed from main."
+              exit 1
+            fi
+
+            echo "should_publish=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          if [ -z "${BEFORE_SHA}" ] || [ "${BEFORE_SHA}" = "0000000000000000000000000000000000000000" ]; then
+            echo "should_publish=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          PREVIOUS_VERSION="$(git show "${BEFORE_SHA}:package.json" | node -e 'let data=""; process.stdin.on("data", chunk => data += chunk); process.stdin.on("end", () => process.stdout.write(JSON.parse(data).version));')"
+
+          if [ "${PREVIOUS_VERSION}" = "${VERSION}" ]; then
+            echo "Version is unchanged at ${VERSION}; skipping publish."
+            echo "should_publish=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "Version changed from ${PREVIOUS_VERSION} to ${VERSION}."
+            echo "should_publish=true" >> "$GITHUB_OUTPUT"
+          fi
+
       - name: Setup Node
+        if: steps.release.outputs.should_publish == 'true'
         uses: actions/setup-node@v4
         with:
           node-version: 24
@@ -88,36 +77,57 @@ jobs:
           registry-url: https://registry.npmjs.org
 
       - name: Install dependencies
+        if: steps.release.outputs.should_publish == 'true'
         run: npm ci
 
       - name: Run automated test suite
+        if: steps.release.outputs.should_publish == 'true'
         run: npm run test:ci
 
-      - name: Bump package version
-        run: npm version "${{ inputs.release_type }}" --no-git-tag-version
-
-      - name: Read new version
-        id: version
+      - name: Check whether version already exists on npm
+        if: steps.release.outputs.should_publish == 'true'
+        id: npm-check
+        env:
+          PACKAGE_NAME: ${{ steps.release.outputs.package_name }}
+          VERSION: ${{ steps.release.outputs.version }}
         run: |
-          echo "value=$(node -p 'require(\"./package.json\").version')" >> "$GITHUB_OUTPUT"
+          if npm view "${PACKAGE_NAME}@${VERSION}" version >/dev/null 2>&1; then
+            echo "should_publish=false" >> "$GITHUB_OUTPUT"
+            echo "Version ${VERSION} is already published to npm."
+          else
+            echo "should_publish=true" >> "$GITHUB_OUTPUT"
+            echo "Version ${VERSION} is not yet published to npm."
+          fi
 
-      - name: Configure git author
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+      - name: Publish to npm with trusted publishing
+        if: steps.release.outputs.should_publish == 'true' && steps.npm-check.outputs.should_publish == 'true'
+        run: npm publish
 
-      - name: Commit release version
+      - name: Tag published version
+        if: steps.release.outputs.should_publish == 'true' && steps.npm-check.outputs.should_publish == 'true'
         env:
-          VERSION: ${{ steps.version.outputs.value }}
+          VERSION: ${{ steps.release.outputs.version }}
         run: |
-          git add package.json package-lock.json
-          git commit -m "chore(release): v${VERSION}"
-          git tag "v${VERSION}"
+          if git rev-parse "v${VERSION}" >/dev/null 2>&1; then
+            echo "Tag v${VERSION} already exists locally."
+            exit 0
+          fi
 
-      - name: Publish to npm with trusted publishing
-        run: npm publish
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag "v${VERSION}"
+          git push origin "refs/tags/v${VERSION}"
 
-      - name: Push release commit and tag
+      - name: Write job summary
         env:
-          VERSION: ${{ steps.version.outputs.value }}
-        run: git push --atomic origin "HEAD:${GITHUB_REF_NAME}" "refs/tags/v${VERSION}"
+          VERSION: ${{ steps.release.outputs.version }}
+          SHOULD_PUBLISH: ${{ steps.release.outputs.should_publish }}
+          NPM_PUBLISH: ${{ steps.npm-check.outputs.should_publish }}
+        run: |
+          {
+            echo "## Publish summary"
+            echo
+            echo "- Version: \`${VERSION}\`"
+            echo "- Trigger requested publish: \`${SHOULD_PUBLISH:-false}\`"
+            echo "- npm publish executed: \`${NPM_PUBLISH:-false}\`"
+          } >> "$GITHUB_STEP_SUMMARY"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "periapsis",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "private": false,
   "type": "module",
   "scripts": {