From de9220b8c6246b33953d154b123a170f25d68129 Mon Sep 17 00:00:00 2001 From: boalambo Date: Fri, 25 Sep 2026 10:59:05 +0100 Subject: [PATCH 1/3] ci: pin docs validation to exact published SDK version - Add extract-sdk-version job to dynamically read SDK version from package.json - Download published SDK artifact as .tgz before installing - Install packed artifact instead of registry version to ensure exact match - Record tested SDK version in CI output for all validation jobs - Add sdk-version-check workflow to verify version exists on npm before allowing package.json changes - Pin SDK version to exact version (1.4.5) instead of caret range - Add documentation for SDK version update process This ensures docs snippets and tests always validate against the exact published SDK version, preventing issues where local or floating versions differ from published releases. --- .github/workflows/sdk-version-check.yml | 47 ++++++++++++++++ .github/workflows/snippets.yml | 72 ++++++++++++++++++++++--- docs/SDK_VERSION_UPDATE.md | 37 +++++++++++++ package.json | 2 +- 4 files changed, 151 insertions(+), 7 deletions(-) create mode 100644 .github/workflows/sdk-version-check.yml create mode 100644 docs/SDK_VERSION_UPDATE.md diff --git a/.github/workflows/sdk-version-check.yml b/.github/workflows/sdk-version-check.yml new file mode 100644 index 0000000..cef2fae --- /dev/null +++ b/.github/workflows/sdk-version-check.yml @@ -0,0 +1,47 @@ +name: SDK Version Check + +on: + pull_request: + paths: + - 'package.json' + +jobs: + check-sdk-version: + name: Verify SDK version exists on npm + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version: 22 + + - name: Extract SDK version from package.json + id: extract-version + run: | + VERSION=$(node -p "require('./package.json').dependencies['@wraith-protocol/sdk']") + echo "version=$VERSION" >> $GITHUB_OUTPUT + echo "Detected SDK version: $VERSION" + + - name: Check if version exists on npm + id: check + run: | + VERSION="${{ steps.extract-version.outputs.version }}" + echo "Checking if @wraith-protocol/sdk@$VERSION exists on npm..." + + if npm view @wraith-protocol/sdk@$VERSION version > /dev/null 2>&1; then + echo "✅ Version $VERSION exists on npm" + echo "version=$VERSION" >> $GITHUB_OUTPUT + else + echo "❌ Version $VERSION does not exist on npm" + echo "Please ensure the SDK version is published before updating docs" + echo "Run: npm view @wraith-protocol/sdk versions" + exit 1 + fi + + - name: Output verified version + run: | + echo "Verified SDK version: ${{ steps.check.outputs.version }}" + echo "This version will be used for all docs validation checks" diff --git a/.github/workflows/snippets.yml b/.github/workflows/snippets.yml index 196cc57..874c20a 100644 --- a/.github/workflows/snippets.yml +++ b/.github/workflows/snippets.yml @@ -8,9 +8,31 @@ on: - main jobs: + extract-sdk-version: + name: Extract SDK version + runs-on: ubuntu-latest + outputs: + sdk-version: ${{ steps.version.outputs.version }} + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version: 22 + + - name: Extract SDK version from package.json + id: version + run: | + VERSION=$(node -p "require('./package.json').dependencies['@wraith-protocol/sdk']") + echo "version=$VERSION" >> $GITHUB_OUTPUT + echo "Detected SDK version: $VERSION" + check-snippets: name: Compile docs snippets runs-on: ubuntu-latest + needs: extract-sdk-version steps: - name: Checkout uses: actions/checkout@v4 @@ -26,8 +48,20 @@ jobs: node-version: 22 cache: pnpm - - name: Install dependencies - run: pnpm install --frozen-lockfile + - name: Download published SDK artifact + run: | + echo "Downloading @wraith-protocol/sdk@${{ needs.extract-sdk-version.outputs.sdk-version }}" + pnpm pack @wraith-protocol/sdk@${{ needs.extract-sdk-version.outputs.sdk-version }} --pack-destination /tmp/sdk.tgz + + - name: Install dependencies with pinned SDK + run: | + pnpm install --frozen-lockfile + pnpm remove @wraith-protocol/sdk + pnpm add /tmp/sdk.tgz + + - name: Record tested SDK version + run: | + echo "Testing against SDK version: ${{ needs.extract-sdk-version.outputs.sdk-version }}" - name: Check snippets run: pnpm run check:snippets @@ -42,6 +76,7 @@ jobs: name: Stellar snippet testnet validation runs-on: ubuntu-latest continue-on-error: true + needs: extract-sdk-version steps: - name: Checkout uses: actions/checkout@v4 @@ -57,8 +92,20 @@ jobs: node-version: 22 cache: pnpm - - name: Install dependencies - run: pnpm install --frozen-lockfile + - name: Download published SDK artifact + run: | + echo "Downloading @wraith-protocol/sdk@${{ needs.extract-sdk-version.outputs.sdk-version }}" + pnpm pack @wraith-protocol/sdk@${{ needs.extract-sdk-version.outputs.sdk-version }} --pack-destination /tmp/sdk.tgz + + - name: Install dependencies with pinned SDK + run: | + pnpm install --frozen-lockfile + pnpm remove @wraith-protocol/sdk + pnpm add /tmp/sdk.tgz + + - name: Record tested SDK version + run: | + echo "Testing against SDK version: ${{ needs.extract-sdk-version.outputs.sdk-version }}" - name: Validate Stellar testnet snippets run: pnpm run check:stellar-testnet @@ -66,6 +113,7 @@ jobs: playground-smoke: name: Playground smoke test runs-on: ubuntu-latest + needs: extract-sdk-version steps: - name: Checkout uses: actions/checkout@v4 @@ -81,8 +129,20 @@ jobs: node-version: 22 cache: pnpm - - name: Install dependencies - run: pnpm install --frozen-lockfile + - name: Download published SDK artifact + run: | + echo "Downloading @wraith-protocol/sdk@${{ needs.extract-sdk-version.outputs.sdk-version }}" + pnpm pack @wraith-protocol/sdk@${{ needs.extract-sdk-version.outputs.sdk-version }} --pack-destination /tmp/sdk.tgz + + - name: Install dependencies with pinned SDK + run: | + pnpm install --frozen-lockfile + pnpm remove @wraith-protocol/sdk + pnpm add /tmp/sdk.tgz + + - name: Record tested SDK version + run: | + echo "Testing against SDK version: ${{ needs.extract-sdk-version.outputs.sdk-version }}" - name: Verify playground fixtures are in sync run: pnpm run check:playground-fixtures diff --git a/docs/SDK_VERSION_UPDATE.md b/docs/SDK_VERSION_UPDATE.md new file mode 100644 index 0000000..7b98d40 --- /dev/null +++ b/docs/SDK_VERSION_UPDATE.md @@ -0,0 +1,37 @@ +# Updating SDK Version in Docs + +When updating the `@wraith-protocol/sdk` version in the docs repository, follow these steps: + +## Prerequisites + +1. Ensure the new SDK version is published to npm +2. Verify the version exists: `npm view @wraith-protocol/sdk versions` + +## Update Process + +1. Update the version in `package.json`: + ```json + "dependencies": { + "@wraith-protocol/sdk": "X.Y.Z" + } + ``` + +2. Commit the change (the SDK version check workflow will verify the version exists) + +3. Update the lockfile: + ```bash + pnpm install + ``` + +4. Commit the updated lockfile + +## CI Behavior + +- The `sdk-version-check.yml` workflow runs on any PR that modifies `package.json` +- It verifies the specified SDK version exists on npm before allowing the PR to proceed +- The `snippets.yml` workflow extracts the version from `package.json` and: + - Downloads the exact published SDK artifact as a `.tgz` file + - Installs the packed artifact instead of the registry version + - Records the tested version in CI output + +This ensures docs validation always runs against the exact published SDK version, not local or floating versions. diff --git a/package.json b/package.json index 5ad813e..df9ea9c 100644 --- a/package.json +++ b/package.json @@ -19,7 +19,7 @@ "dependencies": { "@solana/web3.js": "^1.95.0", "@stellar/stellar-sdk": "^13.1.0", - "@wraith-protocol/sdk": "^1.4.5" + "@wraith-protocol/sdk": "1.4.5" }, "devDependencies": { "@playwright/test": "^1.49.1", From 03fb9ad14d4d8caa763264980f716b5ec8cf8565 Mon Sep 17 00:00:00 2001 From: boalambo Date: Sat, 26 Sep 2026 10:49:33 +0100 Subject: [PATCH 2/3] fix: use npm pack to download SDK from registry - Replace pnpm pack with npm pack to download from npm registry - pnpm pack was trying to pack the local docs project instead - npm pack correctly fetches the published package tarball - Update tarball filename to match npm pack output format --- .github/workflows/snippets.yml | 15 +++++++++------ docs/SDK_VERSION_UPDATE.md | 2 +- 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/.github/workflows/snippets.yml b/.github/workflows/snippets.yml index 874c20a..b787e48 100644 --- a/.github/workflows/snippets.yml +++ b/.github/workflows/snippets.yml @@ -51,13 +51,14 @@ jobs: - name: Download published SDK artifact run: | echo "Downloading @wraith-protocol/sdk@${{ needs.extract-sdk-version.outputs.sdk-version }}" - pnpm pack @wraith-protocol/sdk@${{ needs.extract-sdk-version.outputs.sdk-version }} --pack-destination /tmp/sdk.tgz + cd /tmp + npm pack @wraith-protocol/sdk@${{ needs.extract-sdk-version.outputs.sdk-version }} - name: Install dependencies with pinned SDK run: | pnpm install --frozen-lockfile pnpm remove @wraith-protocol/sdk - pnpm add /tmp/sdk.tgz + pnpm add /tmp/wraith-protocol-sdk-${{ needs.extract-sdk-version.outputs.sdk-version }}.tgz - name: Record tested SDK version run: | @@ -95,13 +96,14 @@ jobs: - name: Download published SDK artifact run: | echo "Downloading @wraith-protocol/sdk@${{ needs.extract-sdk-version.outputs.sdk-version }}" - pnpm pack @wraith-protocol/sdk@${{ needs.extract-sdk-version.outputs.sdk-version }} --pack-destination /tmp/sdk.tgz + cd /tmp + npm pack @wraith-protocol/sdk@${{ needs.extract-sdk-version.outputs.sdk-version }} - name: Install dependencies with pinned SDK run: | pnpm install --frozen-lockfile pnpm remove @wraith-protocol/sdk - pnpm add /tmp/sdk.tgz + pnpm add /tmp/wraith-protocol-sdk-${{ needs.extract-sdk-version.outputs.sdk-version }}.tgz - name: Record tested SDK version run: | @@ -132,13 +134,14 @@ jobs: - name: Download published SDK artifact run: | echo "Downloading @wraith-protocol/sdk@${{ needs.extract-sdk-version.outputs.sdk-version }}" - pnpm pack @wraith-protocol/sdk@${{ needs.extract-sdk-version.outputs.sdk-version }} --pack-destination /tmp/sdk.tgz + cd /tmp + npm pack @wraith-protocol/sdk@${{ needs.extract-sdk-version.outputs.sdk-version }} - name: Install dependencies with pinned SDK run: | pnpm install --frozen-lockfile pnpm remove @wraith-protocol/sdk - pnpm add /tmp/sdk.tgz + pnpm add /tmp/wraith-protocol-sdk-${{ needs.extract-sdk-version.outputs.sdk-version }}.tgz - name: Record tested SDK version run: | diff --git a/docs/SDK_VERSION_UPDATE.md b/docs/SDK_VERSION_UPDATE.md index 7b98d40..a64f194 100644 --- a/docs/SDK_VERSION_UPDATE.md +++ b/docs/SDK_VERSION_UPDATE.md @@ -30,7 +30,7 @@ When updating the `@wraith-protocol/sdk` version in the docs repository, follow - The `sdk-version-check.yml` workflow runs on any PR that modifies `package.json` - It verifies the specified SDK version exists on npm before allowing the PR to proceed - The `snippets.yml` workflow extracts the version from `package.json` and: - - Downloads the exact published SDK artifact as a `.tgz` file + - Downloads the exact published SDK artifact as a `.tgz` file using `npm pack` - Installs the packed artifact instead of the registry version - Records the tested version in CI output From e6977fcc5b68e98a30e972f69c3957012a29b7b9 Mon Sep 17 00:00:00 2001 From: boalambo Date: Mon, 28 Sep 2026 13:59:24 +0100 Subject: [PATCH 3/3] fix: update lockfile to match exact SDK version - Regenerate pnpm-lock.yaml to reflect exact version 1.4.5 instead of ^1.4.5 - This resolves CI failure where lockfile didn't match package.json --- pnpm-lock.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 8ecd561..58414f5 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -15,7 +15,7 @@ importers: specifier: ^13.1.0 version: 13.3.0 '@wraith-protocol/sdk': - specifier: ^1.4.5 + specifier: 1.4.5 version: 1.4.5(@solana/web3.js@1.98.4(bufferutil@4.1.0)(typescript@5.9.3)(utf-8-validate@6.0.6))(@stellar/stellar-sdk@13.3.0)(bufferutil@4.1.0)(typescript@5.9.3)(utf-8-validate@6.0.6) devDependencies: '@playwright/test':