From c9e4ed3df6c85c9556c36b934ce8da1ee9ecdb5f Mon Sep 17 00:00:00 2001
From: Edgars <edgars@genlayerlabs.com>
Date: Wed, 8 Jul 2026 22:39:44 +0100
Subject: [PATCH 1/2] ci: add clarke cli tarball release

---
 .github/workflows/clarke-tarball-release.yml | 127 +++++++++++++++++++
 1 file changed, 127 insertions(+)
 create mode 100644 .github/workflows/clarke-tarball-release.yml

diff --git a/.github/workflows/clarke-tarball-release.yml b/.github/workflows/clarke-tarball-release.yml
new file mode 100644
index 00000000..a5066628
--- /dev/null
+++ b/.github/workflows/clarke-tarball-release.yml
@@ -0,0 +1,127 @@
+name: Clarke CLI Tarball Release
+
+# Manual, no-npm prerelease packaging path.
+#
+# This intentionally does not use v* tags because publish.yml owns those and
+# publishes to npm. Clarke tags use the clarke-cli-* prefix and only create a
+# GitHub prerelease with an npm-installable tarball asset.
+on:
+  workflow_dispatch:
+    inputs:
+      source_ref:
+        description: "Git ref to package"
+        required: true
+        default: "v0.40-dev"
+      package_version:
+        description: "Version stamped into the tarball package.json"
+        required: true
+        default: "0.40.0-clarke.0"
+      tag_name:
+        description: "GitHub Release tag to create; must start with clarke-cli-"
+        required: true
+        default: "clarke-cli-0.40.0-clarke.0"
+      replace_existing:
+        description: "Delete and recreate an existing prerelease/tag"
+        required: true
+        type: boolean
+        default: false
+
+permissions:
+  contents: write
+
+jobs:
+  pack-release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate inputs
+        run: |
+          set -euo pipefail
+          case "${{ inputs.tag_name }}" in
+            clarke-cli-*) ;;
+            *)
+              echo "tag_name must start with clarke-cli- so publish.yml cannot pick it up." >&2
+              exit 1
+              ;;
+          esac
+
+          node -e "const v = '${{ inputs.package_version }}'; if (!/^[0-9]+\\.[0-9]+\\.[0-9]+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$/.test(v)) { console.error('Invalid semver: ' + v); process.exit(1); }"
+
+      - name: Checkout source ref
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.source_ref }}
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Stamp prerelease version
+        run: npm version "${{ inputs.package_version }}" --no-git-tag-version --allow-same-version
+
+      - name: Build CLI
+        run: npm run build
+
+      - name: Pack tarball
+        id: pack
+        run: |
+          set -euo pipefail
+          mkdir -p "$RUNNER_TEMP/artifacts"
+          tarball="$(npm pack --pack-destination "$RUNNER_TEMP/artifacts" | tail -n 1)"
+          echo "tarball=$tarball" >> "$GITHUB_OUTPUT"
+          echo "path=$RUNNER_TEMP/artifacts/$tarball" >> "$GITHUB_OUTPUT"
+          ls -lh "$RUNNER_TEMP/artifacts/$tarball"
+
+      - name: Verify tarball install
+        run: |
+          set -euo pipefail
+          prefix="$RUNNER_TEMP/install"
+          npm install -g --prefix "$prefix" "${{ steps.pack.outputs.path }}"
+          "$prefix/bin/genlayer" --version
+          "$prefix/bin/genlayer" network --help >/dev/null
+          "$prefix/bin/genlayer" vesting --help >/dev/null
+
+      - name: Create prerelease
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG_NAME: ${{ inputs.tag_name }}
+          PACKAGE_VERSION: ${{ inputs.package_version }}
+          SOURCE_REF: ${{ inputs.source_ref }}
+          REPLACE_EXISTING: ${{ inputs.replace_existing }}
+          TARBALL_PATH: ${{ steps.pack.outputs.path }}
+        run: |
+          set -euo pipefail
+          source_sha="$(git rev-parse HEAD)"
+
+          if gh release view "$TAG_NAME" >/dev/null 2>&1; then
+            if [ "$REPLACE_EXISTING" != "true" ]; then
+              echo "Release $TAG_NAME already exists. Re-run with replace_existing=true to recreate it." >&2
+              exit 1
+            fi
+            gh release delete "$TAG_NAME" --cleanup-tag --yes
+          fi
+
+          notes="$(cat <<EOF
+          Clarke CLI prerelease tarball.
+
+          Source ref: $SOURCE_REF
+          Source SHA: $source_sha
+          Package version: $PACKAGE_VERSION
+
+          Install:
+
+              npm install -g https://github.com/genlayerlabs/genlayer-cli/releases/download/$TAG_NAME/$(basename "$TARBALL_PATH")
+
+          This release intentionally does not publish to npm.
+          EOF
+          )"
+
+          gh release create "$TAG_NAME" "$TARBALL_PATH" \
+            --target "$source_sha" \
+            --title "Clarke CLI $PACKAGE_VERSION" \
+            --notes "$notes" \
+            --prerelease

From 7aa1712331580858d6031296a00325c2e7be9b6e Mon Sep 17 00:00:00 2001
From: Edgars <edgars@genlayerlabs.com>
Date: Wed, 8 Jul 2026 22:45:43 +0100
Subject: [PATCH 2/2] ci: publish prereleases to npm dist tags

---
 .github/workflows/clarke-tarball-release.yml | 127 -------------------
 .github/workflows/publish.yml                |  50 +++++++-
 2 files changed, 47 insertions(+), 130 deletions(-)
 delete mode 100644 .github/workflows/clarke-tarball-release.yml

diff --git a/.github/workflows/clarke-tarball-release.yml b/.github/workflows/clarke-tarball-release.yml
deleted file mode 100644
index a5066628..00000000
--- a/.github/workflows/clarke-tarball-release.yml
+++ /dev/null
@@ -1,127 +0,0 @@
-name: Clarke CLI Tarball Release
-
-# Manual, no-npm prerelease packaging path.
-#
-# This intentionally does not use v* tags because publish.yml owns those and
-# publishes to npm. Clarke tags use the clarke-cli-* prefix and only create a
-# GitHub prerelease with an npm-installable tarball asset.
-on:
-  workflow_dispatch:
-    inputs:
-      source_ref:
-        description: "Git ref to package"
-        required: true
-        default: "v0.40-dev"
-      package_version:
-        description: "Version stamped into the tarball package.json"
-        required: true
-        default: "0.40.0-clarke.0"
-      tag_name:
-        description: "GitHub Release tag to create; must start with clarke-cli-"
-        required: true
-        default: "clarke-cli-0.40.0-clarke.0"
-      replace_existing:
-        description: "Delete and recreate an existing prerelease/tag"
-        required: true
-        type: boolean
-        default: false
-
-permissions:
-  contents: write
-
-jobs:
-  pack-release:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Validate inputs
-        run: |
-          set -euo pipefail
-          case "${{ inputs.tag_name }}" in
-            clarke-cli-*) ;;
-            *)
-              echo "tag_name must start with clarke-cli- so publish.yml cannot pick it up." >&2
-              exit 1
-              ;;
-          esac
-
-          node -e "const v = '${{ inputs.package_version }}'; if (!/^[0-9]+\\.[0-9]+\\.[0-9]+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$/.test(v)) { console.error('Invalid semver: ' + v); process.exit(1); }"
-
-      - name: Checkout source ref
-        uses: actions/checkout@v4
-        with:
-          ref: ${{ inputs.source_ref }}
-
-      - name: Set up Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: "24"
-          cache: npm
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Stamp prerelease version
-        run: npm version "${{ inputs.package_version }}" --no-git-tag-version --allow-same-version
-
-      - name: Build CLI
-        run: npm run build
-
-      - name: Pack tarball
-        id: pack
-        run: |
-          set -euo pipefail
-          mkdir -p "$RUNNER_TEMP/artifacts"
-          tarball="$(npm pack --pack-destination "$RUNNER_TEMP/artifacts" | tail -n 1)"
-          echo "tarball=$tarball" >> "$GITHUB_OUTPUT"
-          echo "path=$RUNNER_TEMP/artifacts/$tarball" >> "$GITHUB_OUTPUT"
-          ls -lh "$RUNNER_TEMP/artifacts/$tarball"
-
-      - name: Verify tarball install
-        run: |
-          set -euo pipefail
-          prefix="$RUNNER_TEMP/install"
-          npm install -g --prefix "$prefix" "${{ steps.pack.outputs.path }}"
-          "$prefix/bin/genlayer" --version
-          "$prefix/bin/genlayer" network --help >/dev/null
-          "$prefix/bin/genlayer" vesting --help >/dev/null
-
-      - name: Create prerelease
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          TAG_NAME: ${{ inputs.tag_name }}
-          PACKAGE_VERSION: ${{ inputs.package_version }}
-          SOURCE_REF: ${{ inputs.source_ref }}
-          REPLACE_EXISTING: ${{ inputs.replace_existing }}
-          TARBALL_PATH: ${{ steps.pack.outputs.path }}
-        run: |
-          set -euo pipefail
-          source_sha="$(git rev-parse HEAD)"
-
-          if gh release view "$TAG_NAME" >/dev/null 2>&1; then
-            if [ "$REPLACE_EXISTING" != "true" ]; then
-              echo "Release $TAG_NAME already exists. Re-run with replace_existing=true to recreate it." >&2
-              exit 1
-            fi
-            gh release delete "$TAG_NAME" --cleanup-tag --yes
-          fi
-
-          notes="$(cat <<EOF
-          Clarke CLI prerelease tarball.
-
-          Source ref: $SOURCE_REF
-          Source SHA: $source_sha
-          Package version: $PACKAGE_VERSION
-
-          Install:
-
-              npm install -g https://github.com/genlayerlabs/genlayer-cli/releases/download/$TAG_NAME/$(basename "$TARBALL_PATH")
-
-          This release intentionally does not publish to npm.
-          EOF
-          )"
-
-          gh release create "$TAG_NAME" "$TARBALL_PATH" \
-            --target "$source_sha" \
-            --title "Clarke CLI $PACKAGE_VERSION" \
-            --notes "$notes" \
-            --prerelease
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index a8c7dea2..e5e27ca3 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -7,6 +7,11 @@ name: Publish Package to NPM
 # workflow fires on the tag push, sanity-checks the tag matches
 # package.json, builds, publishes to npm, and creates the GitHub
 # Release. It never bumps or tags by itself.
+#
+# Stable tags such as v0.39.2 publish to npm's latest dist-tag.
+# Prerelease tags such as v0.40.0-rc1 publish to a matching prerelease
+# dist-tag (rc1) and create a GitHub prerelease. Prereleases must never
+# become latest.
 on:
   workflow_dispatch:
   push:
@@ -32,8 +37,14 @@ jobs:
 
       - run: npm ci
 
-      - name: Verify tag matches package.json version
+      - name: Verify tag and resolve npm dist-tag
+        id: version
         run: |
+          if [ "${GITHUB_REF_TYPE:-}" != "tag" ]; then
+            echo "Publish must run from a git tag. Current ref type: ${GITHUB_REF_TYPE:-unknown}" >&2
+            exit 1
+          fi
+
           TAG_VERSION="${GITHUB_REF_NAME#v}"
           PKG_VERSION="$(node -p "require('./package.json').version")"
           if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
@@ -41,12 +52,34 @@ jobs:
             echo "Re-cut the release via scripts/release.sh so the tag and the committed version match." >&2
             exit 1
           fi
+
+          IS_PRERELEASE=false
+          NPM_DIST_TAG=latest
+          if [[ "$TAG_VERSION" == *-* ]]; then
+            IS_PRERELEASE=true
+            NPM_DIST_TAG="${TAG_VERSION#*-}"
+            NPM_DIST_TAG="${NPM_DIST_TAG%%+*}"
+
+            if [ -z "$NPM_DIST_TAG" ] || [ "$NPM_DIST_TAG" = "latest" ]; then
+              echo "Invalid prerelease npm dist-tag: '$NPM_DIST_TAG'" >&2
+              exit 1
+            fi
+
+            if [[ "$NPM_DIST_TAG" =~ ^v?[0-9] ]]; then
+              echo "Invalid prerelease npm dist-tag '$NPM_DIST_TAG': dist-tags must not look like versions." >&2
+              exit 1
+            fi
+          fi
+
           echo "Tag $GITHUB_REF_NAME matches package.json $PKG_VERSION."
+          echo "npm dist-tag: $NPM_DIST_TAG"
+          echo "is_prerelease=$IS_PRERELEASE" >> "$GITHUB_OUTPUT"
+          echo "npm_dist_tag=$NPM_DIST_TAG" >> "$GITHUB_OUTPUT"
 
       - run: npm run build
 
       - name: Publish to npm
-        run: npm publish --provenance --access public
+        run: npm publish --provenance --access public --tag "${{ steps.version.outputs.npm_dist_tag }}"
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
@@ -62,6 +95,17 @@ jobs:
           if [ -z "$NOTES" ]; then
             NOTES="Release $GITHUB_REF_NAME"
           fi
+
+          NOTES="$NOTES
+
+          npm install -g genlayer@${{ steps.version.outputs.npm_dist_tag }}"
+
+          RELEASE_FLAGS=()
+          if [ "${{ steps.version.outputs.is_prerelease }}" = "true" ]; then
+            RELEASE_FLAGS+=(--prerelease)
+          fi
+
           gh release create "$GITHUB_REF_NAME" \
             --title "$GITHUB_REF_NAME" \
-            --notes "$NOTES"
+            --notes "$NOTES" \
+            "${RELEASE_FLAGS[@]}"