chore: add deployment guide and CI/CD workflows for npm publishing

.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '26'
+          cache: 'pnpm'
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v3
+        with:
+          version: 10.13.1
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Lint code
+        run: pnpm lint
+
+      - name: Build project
+        run: pnpm build
+
+      - name: Run tests
+        run: pnpm test
+
+      - name: Verify build artifacts
+        run: |
+          test -f dist/index.js || (echo "dist/index.js not found" && exit 1)
+          test -d dist || (echo "dist directory not found" && exit 1)
+          test -d templates || (echo "templates directory not found" && exit 1)
+          echo "Build artifacts verified successfully"
+
+      - name: Test CLI installation
+        run: |
+          npm pack
+          npm install -g ./celo-celo-composer-*.tgz
+          celo-composer --help
+          npm uninstall -g celo-composer || true
+          rm -f celo-celo-composer-*.tgz
+

.github/workflows/publish-beta.yml

@@ -0,0 +1,115 @@
+name: Publish Beta to NPM
+
+on:
+  push:
+    tags:
+      - 'v*-beta*'
+      - 'v*-alpha*'
+      - 'v*-rc*'
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Beta version to publish (e.g., 2.4.13-beta.1)'
+        required: true
+        default: '2.4.13-beta.1'
+      tag:
+        description: 'NPM dist-tag (beta, alpha, rc)'
+        required: true
+        default: 'beta'
+
+jobs:
+  publish-beta:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '26'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'pnpm'
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v3
+        with:
+          version: 10.13.1
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Lint code
+        run: pnpm lint
+
+      - name: Build project
+        run: pnpm build
+
+      - name: Run tests
+        run: pnpm test
+
+      - name: Determine dist-tag
+        id: dist-tag
+        run: |
+          if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
+            echo "tag=${{ github.event.inputs.tag }}" >> $GITHUB_OUTPUT
+          else
+            # Extract tag from git tag (e.g., v2.4.13-beta.1 -> beta)
+            TAG_NAME=${GITHUB_REF#refs/tags/v}
+            if [[ $TAG_NAME == *"-beta"* ]]; then
+              echo "tag=beta" >> $GITHUB_OUTPUT
+            elif [[ $TAG_NAME == *"-alpha"* ]]; then
+              echo "tag=alpha" >> $GITHUB_OUTPUT
+            elif [[ $TAG_NAME == *"-rc"* ]]; then
+              echo "tag=rc" >> $GITHUB_OUTPUT
+            else
+              echo "tag=beta" >> $GITHUB_OUTPUT
+            fi
+          fi
+
+      - name: Update version (if manual dispatch)
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          npm version ${{ github.event.inputs.version }} --no-git-tag-version
+
+      - name: Publish to NPM (Pre-release)
+        run: npm publish --tag ${{ steps.dist-tag.outputs.tag }}
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create GitHub Pre-release
+        run: |
+          gh release create ${{ github.ref_name }} \
+            --title "Release ${{ github.ref_name }} (Pre-release)" \
+            --prerelease \
+            --notes "## Pre-release Version ${{ github.ref_name }}
+
+          ⚠️ **This is a pre-release version** - use with caution in production environments.
+
+          ## Installation
+
+          \`\`\`bash
+          npm install -g @celo/celo-composer@${{ steps.dist-tag.outputs.tag }}
+          \`\`\`
+
+          ## Usage
+
+          \`\`\`bash
+          npx @celo/celo-composer@${{ steps.dist-tag.outputs.tag }} create my-celo-app
+          \`\`\`
+
+          ## Changes in this Pre-release
+
+          See [CHANGELOG.md](https://github.com/celo-org/celo-composer/blob/${{ github.ref_name }}/CHANGELOG.md) for detailed changes.
+
+          ## Feedback
+
+          Please report any issues or feedback on our [GitHub Issues](https://github.com/celo-org/celo-composer/issues)."
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+

.github/workflows/publish.yml

@@ -0,0 +1,93 @@
+name: Publish to NPM
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to publish (e.g., 2.4.13)'
+        required: true
+        default: '2.4.13'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    # Skip if tag is a pre-release (beta/alpha/rc)
+    if: github.event_name == 'workflow_dispatch' || (github.event_name == 'push' && !contains(github.ref_name, '-beta') && !contains(github.ref_name, '-alpha') && !contains(github.ref_name, '-rc'))
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '26'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'pnpm'
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v3
+        with:
+          version: 10.13.1
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Lint code
+        run: pnpm lint
+
+      - name: Build project
+        run: pnpm build
+
+      - name: Run tests
+        run: pnpm test
+
+      - name: Extract version from tag
+        id: version
+        if: github.event_name == 'push'
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/v}
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "Extracted version: $VERSION"
+
+      - name: Update version (if manual dispatch)
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          npm version ${{ github.event.inputs.version }} --no-git-tag-version
+          VERSION=${{ github.event.inputs.version }}
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Publish to NPM
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create GitHub Release
+        run: |
+          gh release create ${{ github.ref_name }} \
+            --title "Release ${{ github.ref_name }}" \
+            --notes "## Changes in this Release
+
+          See [CHANGELOG.md](https://github.com/celo-org/celo-composer/blob/${{ github.ref_name }}/CHANGELOG.md) for detailed changes.
+
+          ## Installation
+
+          \`\`\`bash
+          npm install -g @celo/celo-composer
+          \`\`\`
+
+          ## Usage
+
+          \`\`\`bash
+          npx @celo/celo-composer create my-celo-app
+          \`\`\`"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+

DEPLOYMENT.md

@@ -0,0 +1,131 @@
+# Deployment Guide
+
+This document describes the CI/CD workflows for the `@celo/celo-composer` CLI tool.
+
+## Workflows
+
+### 1. CI Workflow
+
+**Description:**
+Runs automated tests and validation on every push and pull request. This workflow ensures code quality by:
+- Linting TypeScript code
+- Building the project
+- Running tests
+- Verifying build artifacts
+- Testing CLI installation
+
+**How to Trigger:**
+- Automatically runs on push to `main` or `develop` branches
+- Automatically runs on pull requests targeting `main` or `develop` branches
+- No manual action required
+
+**View Results:**
+- Go to the [Actions tab](https://github.com/celo-org/celo-composer/actions) on GitHub
+- Click on any workflow run to see detailed logs
+
+---
+
+### 2. Publish Workflow (Stable Releases)
+
+**Description:**
+Publishes stable releases to npm with the `latest` tag and creates GitHub releases. This workflow:
+- Runs all CI checks (lint, build, test)
+- Publishes the package to npm
+- Creates a GitHub release with release notes
+
+**How to Trigger:**
+
+**Automatic (Recommended):**
+1. Ensure your code is on the `main` branch and all changes are committed and pushed
+2. Make sure `package.json` version is already updated to match the release version / new version (e.g., `2.4.14`)
+3. Create and push a version tag from your local machine:
+   ```bash
+   git tag v2.4.14
+   git push origin v2.4.14
+   ```
+   The workflow will automatically trigger when you push a tag matching `v*` (excluding pre-releases). This does not create any new commit, just trigger deployment workflow.
+
+**Manual:**
+1. Go to [Actions](https://github.com/celo-org/celo-composer/actions) → **Publish to NPM**
+2. Click **Run workflow**
+3. Select the branch (usually `main`)
+4. Enter the version number (e.g., `2.4.14`)
+5. Click **Run workflow**
+
+   **Note:** Manual dispatch will automatically update `package.json` version, but won't create a git tag.
+
+**Notes:**
+- Code should be on the `main` branch (or the branch you're releasing from)
+- Git commands are run from your local machine
+- Tags containing `-beta`, `-alpha`, or `-rc` will be handled by the Publish-beta workflow instead
+
+---
+
+### 3. Publish-beta Workflow (Pre-Releases)
+
+**Description:**
+Publishes pre-releases (beta/alpha/rc) to npm with appropriate dist-tags and creates GitHub pre-releases. This workflow:
+- Automatically detects the dist-tag from the tag name
+- Runs all CI checks
+- Publishes to npm with the appropriate dist-tag (`beta`, `alpha`, or `rc`)
+- Creates a GitHub pre-release
+
+**How to Trigger:**
+
+**Automatic (Recommended):**
+1. Ensure your code is on the `main` branch and all changes are committed and pushed
+2. Make sure `package.json` version is already updated with pre-release/beta version (e.g., `2.4.14-beta.1`)
+3. Create and push a pre-release tag from your local machine:
+   ```bash
+   # Beta release
+   git tag v2.4.14-beta.1
+   git push origin v2.4.14-beta.1
+
+   # Alpha release
+   git tag v2.4.14-alpha.1
+   git push origin v2.4.14-alpha.1
+
+   # Release candidate
+   git tag v2.4.14-rc.1
+   git push origin v2.4.14-rc.1
+   ```
+   The workflow will automatically trigger when you push a tag matching `v*-beta*`, `v*-alpha*`, or `v*-rc*`.
+
+**Manual:**
+1. Go to [Actions](https://github.com/celo-org/celo-composer/actions) → **Publish Beta to NPM**
+2. Click **Run workflow**
+3. Select the branch (usually `main`)
+4. Enter:
+   - **Version**: `2.4.14-beta.1` (or alpha/rc)
+   - **Tag**: `beta` (or `alpha` or `rc`)
+5. Click **Run workflow**
+
+   **Note:** Manual dispatch will automatically update `package.json` version, but won't create a git tag.
+
+**Notes:**
+- Code should be on the `main` branch (or the branch you're releasing from)
+- Git commands are run from your local machine
+- For automatic trigger: You must manually update `package.json` version before creating the tag
+
+**Installation:**
+Users can install pre-releases with:
+```bash
+npm install -g @celo/celo-composer@beta
+npm install -g @celo/celo-composer@alpha
+npm install -g @celo/celo-composer@rc
+```
+
+---
+
+## Version Numbering
+
+Follow [Semantic Versioning](https://semver.org/):
+
+- **Stable releases**: `v2.4.14` (MAJOR.MINOR.PATCH)
+- **Pre-releases**: `v2.4.14-beta.1`, `v2.4.14-alpha.1`, `v2.4.14-rc.1`
+
+## Monitoring
+
+- **GitHub Actions:** https://github.com/celo-org/celo-composer/actions
+- **npm Package:** https://www.npmjs.com/package/@celo/celo-composer
+- **GitHub Releases:** https://github.com/celo-org/celo-composer/releases