release-sdk

name	release-sdk
description	Trigger the @cradleapp/plugin-sdk npm release workflow and monitor it with Cradle

Release Plugin SDK

Trigger wibus-wee/cradle-app's release-plugin-sdk.yml workflow and monitor it until @cradleapp/plugin-sdk is published to npm.

Prerequisites

Before the first CI release, configure npm Trusted publishing on @cradleapp/plugin-sdk:

• Provider: GitHub Actions
• Repository: wibus-wee/cradle-app
• Workflow filename: release-plugin-sdk.yml

If trusted publishing is not configured, CI publish will fail with authentication errors.

Usage

/release-sdk dev          # Dev channel: sdk-dev-YYYYMMDD.N → npm tag dev
/release-sdk 0.2.0        # Release channel: sdk-v0.2.0 → npm tag latest

Rules

• The release entrypoint is the public repo: /Users/wibus/dev/cradle-app.
• Do not create SDK release tags in the private wibus-wee/Cradle repo.
• SDK tags use the sdk- prefix and are independent from desktop v* / dev-* tags.
• Leave unrelated local files alone.
• Use Cradle awaits for workflow completion; do not watch the run with a long polling loop.
• Use only short bounded retries to let GitHub materialize run/check IDs.

Version Logic

• dev creates sdk-dev-YYYYMMDD.N.
  • Use remote tags, not npm versions, to find the next increment.
  • Example: sdk-dev-20260707.1, then sdk-dev-20260707.2.
  • CI publishes npm version 0.0.0-dev.<run_number> with dist-tag dev.
• A release version creates sdk-vX.Y.Z.
  • Accept 0.2.0 or v0.2.0; normalize to sdk-v0.2.0.
  • CI publishes that SemVer with dist-tag latest.

Implementation

When the user runs /release-sdk <arg>, execute these steps in order.

1. Resolve tag

PUBLIC_REPO=/Users/wibus/dev/cradle-app
cd "$PUBLIC_REPO"
git fetch origin main --tags

ARG="<user argument>"

if [ "$ARG" = "dev" ]; then
  DATE=$(date +%Y%m%d)
  LAST=$(
    git ls-remote --tags --refs origin "refs/tags/sdk-dev-${DATE}.*" |
      sed -E "s#.*refs/tags/sdk-dev-${DATE}\\.([0-9]+)#\\1#" |
      sort -n |
      tail -1
  )
  INCREMENT=$(( ${LAST:-0} + 1 ))
  VERSION="${DATE}.${INCREMENT}"
  TAG="sdk-dev-${VERSION}"
  CHANNEL="dev"
else
  VERSION="${ARG#v}"
  if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$ ]]; then
    echo "Release version must be SemVer, for example 0.2.0" >&2
    exit 1
  fi
  TAG="sdk-v${VERSION}"
  CHANNEL="release"
fi

if git ls-remote --exit-code --tags origin "refs/tags/$TAG" >/dev/null 2>&1; then
  echo "Tag already exists: $TAG" >&2
  exit 1
fi

PUBLIC_SHA=$(git rev-parse origin/main)

2. Push public release tag

git tag -a "$TAG" "$PUBLIC_SHA" -m "Release $TAG"
git push origin "$TAG"

3. Register Cradle await

Resolve the workflow run for the tag, then wait on the publish job.

RUN_ID=$(
  gh run list \
    --repo wibus-wee/cradle-app \
    --workflow=release-plugin-sdk.yml \
    --branch "$TAG" \
    --event push \
    --limit 1 \
    --json databaseId \
    --jq '.[0].databaseId // empty'
)

if [ -z "$RUN_ID" ]; then
  echo "Release workflow run is not visible yet for $TAG; retry this lookup shortly." >&2
  exit 1
fi

CHECK_RUN_ID=$(
  gh run view "$RUN_ID" \
    --repo wibus-wee/cradle-app \
    --json jobs \
    --jq '.jobs[] | select(.name == "Publish @cradleapp/plugin-sdk") | .databaseId' |
    head -1
)

if [ -z "$CHECK_RUN_ID" ]; then
  echo "Publish job is not visible yet for $TAG; retry this lookup shortly." >&2
  exit 1
fi

cradle session await github-ci wibus-wee/cradle-app \
  --run-id "$CHECK_RUN_ID" \
  --reason "Waiting for @cradleapp/plugin-sdk npm release $TAG."

After registering the await, end the turn and let Cradle resume the session.

4. Report result after resume

When Cradle resumes, inspect the workflow run:

gh run list \
  --repo wibus-wee/cradle-app \
  --workflow=release-plugin-sdk.yml \
  --branch "$TAG" \
  --event push \
  --limit 1 \
  --json databaseId,status,conclusion,url

If the workflow succeeded, verify the npm package:

if [ "$CHANNEL" = "dev" ]; then
  npm view @cradleapp/plugin-sdk@dev version
else
  npm view @cradleapp/plugin-sdk version
fi

Report success with the npm version and workflow run URL. If the workflow failed, report the run URL and the failing job name.

Notes

• CI publishes npm package name @cradleapp/plugin-sdk; the monorepo workspace package remains @cradle/plugin-sdk.
• Trusted publishing uses OIDC — no NPM_TOKEN secret in GitHub.
• Provenance attestations are generated automatically for GitHub Actions trusted publishes.
• Dev installs: pnpm add -D @cradleapp/plugin-sdk@dev
• Stable installs: pnpm add -D @cradleapp/plugin-sdk