feat: add GitHub workflow and scripts for publishing dev packages to npm

.github/workflows/publish-dev.yml

@@ -0,0 +1,98 @@
+name: Publish Dev Packages
+
+on:
+  #push:
+  #  branches:
+  #    - 'epic-v[0-9]+.[0-9]+.x'
+  workflow_dispatch:
+    inputs:
+      version_suffix:
+        description:
+          'Version and tag suffix (used in tag: dev-{suffix} and version:
+          x.y.z-dev.{suffix}.commit)'
+        required: true
+        type: string
+      reason:
+        description: 'Reason for manual publish'
+        required: false
+        default: 'Manual trigger by maintainer'
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  publish-dev:
+    name: Publish development versions to npm
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22.x'
+          cache: 'pnpm'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build packages
+        run: pnpm build
+
+      - name: Publish dev packages
+        id: publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          VERSION_SUFFIX: ${{ github.event.inputs.version_suffix }}
+        run: pnpm run publish:dev
+
+      - name: Create release summary
+        if: success()
+        run: |
+          echo "## 🚀 Dev Packages Published" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Branch:** \`${GITHUB_REF#refs/heads/}\`" >> $GITHUB_STEP_SUMMARY
+          echo "**Build:** \`${GITHUB_RUN_NUMBER}\`" >> $GITHUB_STEP_SUMMARY
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            echo "**Trigger:** Manual (by ${{ github.actor }})" >> $GITHUB_STEP_SUMMARY
+            echo "**Version Suffix:** ${{ github.event.inputs.version_suffix }}" >> $GITHUB_STEP_SUMMARY
+            echo "**Reason:** ${{ github.event.inputs.reason }}" >> $GITHUB_STEP_SUMMARY
+          fi
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### 📦 Published Packages" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          if [ -n "${{ steps.publish.outputs.published_packages }}" ]; then
+            echo "${{ steps.publish.outputs.published_packages }}" | while IFS= read -r pkg; do
+              if [ -n "$pkg" ]; then
+                echo "- \`$pkg\`" >> $GITHUB_STEP_SUMMARY
+              fi
+            done
+          else
+            echo "- \`@nucypher/shared@dev\`" >> $GITHUB_STEP_SUMMARY
+            echo "- \`@nucypher/taco@dev\`" >> $GITHUB_STEP_SUMMARY
+            echo "- \`@nucypher/taco-auth@dev\`" >> $GITHUB_STEP_SUMMARY
+          fi
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### Installation" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo '```bash' >> $GITHUB_STEP_SUMMARY
+          if [ -n "${{ github.event.inputs.version_suffix }}" ]; then
+            TAG="dev-${{ github.event.inputs.version_suffix }}"
+            echo "pnpm add @nucypher/shared@${TAG}" >> $GITHUB_STEP_SUMMARY
+            echo "pnpm add @nucypher/taco@${TAG}" >> $GITHUB_STEP_SUMMARY
+            echo "pnpm add @nucypher/taco-auth@${TAG}" >> $GITHUB_STEP_SUMMARY
+          else
+            echo 'pnpm add @nucypher/shared@dev' >> $GITHUB_STEP_SUMMARY
+            echo 'pnpm add @nucypher/taco@dev' >> $GITHUB_STEP_SUMMARY
+            echo 'pnpm add @nucypher/taco-auth@dev' >> $GITHUB_STEP_SUMMARY
+          fi
+          echo '```' >> $GITHUB_STEP_SUMMARY

README.md

@@ -16,6 +16,47 @@ Full documentation can be found [here](https://docs.taco.build/).
 pnpm add @nucypher/taco
 ```
 
+### Development Versions
+
+Development versions are available for testing features before official releases. They can be installed using npm tags:
+
+```bash
+# Latest auto-published dev version
+pnpm add @nucypher/taco@dev
+pnpm add @nucypher/taco-auth@dev
+pnpm add @nucypher/shared@dev
+
+# Specific manually-published version with custom tag
+pnpm add @nucypher/taco@dev-access-client
+pnpm add @nucypher/taco-auth@dev-access-client
+pnpm add @nucypher/shared@dev-access-client
+```
+
+**Development version formats:**
+
+*Auto-published (from epic versions branches):*
+```
+{version}-dev.{commit-hash}
+Example: 0.5.1-dev.a1b2c3d4
+```
+
+*Manually published (custom suffix):*
+```
+{version}-dev.{suffix}.{commit-hash}
+Example: 0.5.1-dev.access-client.a1b2c3d4
+```
+
+**When to use dev versions:**
+- ✅ Testing new features
+- ✅ Providing feedback on unreleased features
+- ✅ Testing specific feature branches via custom tags (e.g., `@dev-access-client`)
+
+**When NOT to use dev versions:**
+- ❌ Production environments
+- ❌ Stable development work
+
+**Note:** Dev versions are automatically published when code is merged to `epic-v*.*.x` branches and can be manually published with custom tags. These versions are unstable and may contain breaking changes or even sometimes broken code..
+
 ## Tutorial
 
 To learn more, follow the tutorial at Threshold

package.json

@@ -21,7 +21,8 @@
     "exports:lint": "pnpm run --parallel --aggregate-output --reporter append-only --filter './packages/**' exports:lint",
     "fix": "pnpm format:fix && pnpm lint:fix && pnpm packages:sort",
     "ci:lint": "run-p lint type-check package:check packages:lint exports:lint",
-    "check-examples": "pnpm run --parallel --aggregate-output --reporter append-only --filter './examples/**' --filter './demos/**' check"
+    "check-examples": "pnpm run --parallel --aggregate-output --reporter append-only --filter './examples/**' --filter './demos/**' check",
+    "publish:dev": "bash scripts/publish-dev.sh"
   },
   "dependencies": {
     "@changesets/cli": "^2.28.1",

scripts/publish-dev.sh

@@ -0,0 +1,140 @@
+#!/bin/bash
+set -e
+
+# Script to publish development versions of packages
+# Usage: ./scripts/publish-dev.sh
+
+# Colors for output
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}📦 Publishing development packages...${NC}"
+
+SHORT_HASH=$(git rev-parse --short=8 HEAD)
+
+# Check if VERSION_SUFFIX is provided (manual workflow)
+if [ -n "$VERSION_SUFFIX" ]; then
+  echo -e "${BLUE}Using manual version suffix:${NC} $VERSION_SUFFIX"
+  DEV_TAG="dev-${VERSION_SUFFIX}"
+  # Append 8-character hash from git commit
+  VERSION_ID="${VERSION_SUFFIX}.${SHORT_HASH}"
+else
+  # Auto mode: use only short hash
+  DEV_TAG="dev"
+  VERSION_ID="${SHORT_HASH}"
+fi
+
+echo -e "${BLUE}Tag:${NC} $DEV_TAG"
+echo -e "${BLUE}Version ID:${NC} $VERSION_ID"
+echo ""
+
+# Array to track published packages
+declare -a PUBLISHED_PACKAGES=()
+
+# Function to update package version
+update_package_version() {
+  local package_dir="${1%/}"  # Remove trailing slash
+  local package_json="${package_dir}/package.json"
+
+  if [ -f "$package_json" ]; then
+    # Use ./ prefix for relative paths in require()
+    PACKAGE_NAME=$(node -p "require('./${package_json}').name")
+    CURRENT_VERSION=$(node -p "require('./${package_json}').version")
+
+    # Check if this is the first dev publish (version doesn't have -dev suffix)
+    if [[ ! "$CURRENT_VERSION" =~ -dev\. ]]; then
+      # Dev publish: bump patch version
+      BASE_VERSION=$(node -p "
+        const ver = '${CURRENT_VERSION}'.split('.');
+        const major = ver[0];
+        const minor = ver[1];
+        const patch = ver[2];
+        const newPatch = parseInt(patch.split('-')[0]) + 1;
+        \`\${major}.\${minor}.\${newPatch}\`;
+      ")
+      echo -e "${BLUE}dev publish - bumping patch version${NC}"
+    else
+      # Subsequent dev publish: strip existing -dev.* suffix to prevent duplication
+      BASE_VERSION="${CURRENT_VERSION%%-dev.*}"
+    fi
+
+    DEV_VERSION="${BASE_VERSION}-dev.${VERSION_ID}"
+
+    echo -e "${GREEN}Updating ${PACKAGE_NAME}:${NC} ${CURRENT_VERSION} → ${DEV_VERSION}"
+
+    # Update version in package.json without git tag
+    cd "$package_dir"
+    npm version "$DEV_VERSION" --no-git-tag-version --allow-same-version
+    cd - > /dev/null
+
+    # Track published package info
+    PUBLISHED_PACKAGES+=("${PACKAGE_NAME}@${DEV_VERSION}")
+  fi
+}
+
+# Packages to exclude from publishing
+EXCLUDED_PACKAGES=("pre" "test-utils")
+
+# Function to check if package should be excluded
+is_excluded() {
+  local package_name="$1"
+  for excluded in "${EXCLUDED_PACKAGES[@]}"; do
+    if [ "$package_name" = "$excluded" ]; then
+      return 0  # true, is excluded
+    fi
+  done
+  return 1  # false, not excluded
+}
+
+# Update all publishable packages
+echo -e "${BLUE}Updating package versions...${NC}"
+for package_dir in packages/*/; do
+  package_name=$(basename "$package_dir")
+  if is_excluded "$package_name"; then
+    echo -e "${BLUE}Skipping excluded package:${NC} $package_name"
+    continue
+  fi
+  update_package_version "$package_dir"
+done
+
+echo ""
+echo -e "${BLUE}Publishing packages with '${DEV_TAG}' tag...${NC}"
+
+# Build filter to exclude specific packages
+FILTER_ARGS=""
+for excluded in "${EXCLUDED_PACKAGES[@]}"; do
+  FILTER_ARGS="$FILTER_ARGS --filter '!@nucypher/${excluded}'"
+done
+
+# Publish all packages except excluded ones with the appropriate dev tag
+eval "pnpm -r --filter './packages/**' $FILTER_ARGS publish --tag ${DEV_TAG} --access public --no-git-checks"
+
+echo ""
+echo -e "${BLUE}Restoring original package.json versions...${NC}"
+
+# Restore original versions in package.json files
+git checkout packages/*/package.json 2>/dev/null || true
+
+echo ""
+echo -e "${GREEN}✅ Dev packages published successfully!${NC}"
+echo ""
+echo -e "${BLUE}📦 Published versions:${NC}"
+for pkg in "${PUBLISHED_PACKAGES[@]}"; do
+  echo "  • $pkg"
+done
+
+# Write published packages to file for GitHub Actions to read
+if [ -n "$GITHUB_OUTPUT" ]; then
+  echo "published_packages<<EOF" >> $GITHUB_OUTPUT
+  for pkg in "${PUBLISHED_PACKAGES[@]}"; do
+    echo "$pkg" >> $GITHUB_OUTPUT
+  done
+  echo "EOF" >> $GITHUB_OUTPUT
+fi
+
+echo ""
+echo -e "${BLUE}Install with:${NC}"
+echo "  pnpm add @nucypher/taco@dev"
+echo "  pnpm add @nucypher/shared@dev"
+echo "  pnpm add @nucypher/taco-auth@dev"