chore: github pages for web bundle (#898)

* chore: github pages for web bundle * docs: updated Bundle distribution setup * chore: addressed PR comments --------- Co-authored-by: Murat Ozcan <murat@mac.lan>
2025-12-17 09:45:25 +00:00 · 2025-11-11 13:35:30 -06:00 · 2025-11-11 13:35:30 -06:00 · 449b5b3d29
commit 449b5b3d29
parent 487d1582a0
7 changed files with 492 additions and 17 deletions
--- a/.github/workflows/bundle-latest.yaml
+++ b/.github/workflows/bundle-latest.yaml
@ -0,0 +1,222 @@
+name: Publish Latest Bundles
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch: {}
+
+permissions:
+  contents: write
+
+jobs:
+  bundle-and-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout BMAD-METHOD
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ".nvmrc"
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate bundles
+        run: npm run bundle
+
+      - name: Create bundle distribution structure
+        run: |
+          mkdir -p dist/bundles
+
+          # Copy bundles with clean structure
+          cp -r src/modules/bmm/sub-modules/* dist/bundles/ 2>/dev/null || true
+          cp -r src/modules/bmb/sub-modules/* dist/bundles/ 2>/dev/null || true
+          cp -r src/modules/cis/sub-modules/* dist/bundles/ 2>/dev/null || true
+
+          # Verify bundles were copied (fail if completely empty)
+          if [ ! "$(ls -A dist/bundles)" ]; then
+            echo "❌ ERROR: No bundles found in dist/bundles/"
+            echo "This likely means 'npm run bundle' failed or bundles weren't generated"
+            exit 1
+          fi
+
+          # Count bundles per platform
+          for platform in claude-code chatgpt gemini; do
+            if [ -d "dist/bundles/$platform" ]; then
+              COUNT=$(find dist/bundles/$platform -name '*.md' 2>/dev/null | wc -l)
+              echo "✅ $platform: $COUNT bundles"
+            fi
+          done
+
+          # Create index.html for GitHub Pages
+          cat > dist/bundles/index.html << 'EOF'
+          <!DOCTYPE html>
+          <html>
+          <head>
+            <title>BMAD Bundles - Latest</title>
+            <meta charset="utf-8">
+            <style>
+              body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; max-width: 800px; margin: 50px auto; padding: 20px; }
+              h1 { color: #333; }
+              .platform { margin: 30px 0; padding: 20px; background: #f5f5f5; border-radius: 8px; }
+              .module { margin: 15px 0; }
+              a { color: #0066cc; text-decoration: none; }
+              a:hover { text-decoration: underline; }
+              code { background: #e0e0e0; padding: 2px 6px; border-radius: 3px; }
+              .warning { background: #fff3cd; padding: 15px; border-left: 4px solid #ffc107; margin: 20px 0; }
+            </style>
+          </head>
+          <body>
+            <h1>BMAD Web Bundles - Latest (Main Branch)</h1>
+
+            <div class="warning">
+              <strong>⚠️ Latest Build (Unstable)</strong><br>
+              These bundles are built from the latest main branch commit. For stable releases, visit
+              <a href="https://github.com/bmad-code-org/BMAD-METHOD/releases/latest">GitHub Releases</a>.
+            </div>
+
+            <p><strong>Last Updated:</strong> <code>$TIMESTAMP</code></p>
+            <p><strong>Commit:</strong> <code>$COMMIT_SHA</code></p>
+
+            <h2>Available Platforms</h2>
+
+            <div class="platform">
+              <h3>Claude Code</h3>
+              <div class="module">
+                <strong>BMM (BMad Method)</strong><br>
+                <a href="./claude-code/sub-agents/bmm-agent-pm.md">PM Agent</a> |
+                <a href="./claude-code/sub-agents/bmm-agent-architect.md">Architect</a> |
+                <a href="./claude-code/sub-agents/bmm-agent-tea.md">TEA</a> |
+                <a href="./claude-code/sub-agents/bmm-agent-dev.md">Developer</a> |
+                <a href="./claude-code/sub-agents/">All BMM Agents</a>
+              </div>
+              <div class="module">
+                <strong>BMB (BMad Builder)</strong><br>
+                <a href="./claude-code/sub-agents/bmb-agent-builder.md">Builder Agent</a>
+              </div>
+              <div class="module">
+                <strong>CIS (Creative Intelligence Suite)</strong><br>
+                <a href="./claude-code/sub-agents/">CIS Agents</a>
+              </div>
+            </div>
+
+            <div class="platform">
+              <h3>ChatGPT</h3>
+              <div class="module">
+                <strong>BMM</strong>: <a href="./chatgpt/sub-agents/">Browse BMM Agents</a><br>
+                <strong>BMB</strong>: <a href="./chatgpt/sub-agents/">Browse BMB Agents</a><br>
+                <strong>CIS</strong>: <a href="./chatgpt/sub-agents/">Browse CIS Agents</a>
+              </div>
+            </div>
+
+            <div class="platform">
+              <h3>Gemini</h3>
+              <div class="module">
+                <strong>BMM</strong>: <a href="./gemini/sub-agents/">Browse BMM Agents</a><br>
+                <strong>BMB</strong>: <a href="./gemini/sub-agents/">Browse BMB Agents</a><br>
+                <strong>CIS</strong>: <a href="./gemini/sub-agents/">Browse CIS Agents</a>
+              </div>
+            </div>
+
+            <h2>Usage</h2>
+            <p>Copy the raw markdown URL and paste into your AI platform's custom instructions or project knowledge.</p>
+            <p>Example: <code>https://raw.githubusercontent.com/bmad-code-org/bmad-bundles/main/claude-code/sub-agents/bmm-agent-pm.md</code></p>
+
+            <h2>Installation (Recommended)</h2>
+            <p>For full IDE integration with slash commands, use the installer:</p>
+            <pre>npx bmad-method@alpha install</pre>
+
+            <footer style="margin-top: 50px; padding-top: 20px; border-top: 1px solid #ccc; color: #666;">
+              <p>Built from <a href="https://github.com/bmad-code-org/BMAD-METHOD">BMAD-METHOD</a> repository.</p>
+            </footer>
+          </body>
+          </html>
+          EOF
+
+          # Replace placeholders
+          TIMESTAMP=$(date -u +"%Y-%m-%d %H:%M UTC")
+          COMMIT_SHA=$(git rev-parse --short HEAD)
+          sed -i "s/\$TIMESTAMP/$TIMESTAMP/" dist/bundles/index.html
+          sed -i "s/\$COMMIT_SHA/$COMMIT_SHA/" dist/bundles/index.html
+
+      - name: Checkout bmad-bundles repo
+        uses: actions/checkout@v4
+        with:
+          repository: bmad-code-org/bmad-bundles
+          path: bmad-bundles
+          token: ${{ secrets.BUNDLES_PAT }}
+
+      - name: Update bundles
+        run: |
+          # Clear old bundles
+          rm -rf bmad-bundles/*
+
+          # Copy new bundles
+          cp -r dist/bundles/* bmad-bundles/
+
+          # Create .nojekyll for GitHub Pages
+          touch bmad-bundles/.nojekyll
+
+          # Create README
+          cat > bmad-bundles/README.md << 'EOF'
+          # BMAD Web Bundles (Latest)
+
+          **⚠️ Unstable Build**: These bundles are auto-generated from the latest `main` branch.
+
+          For stable releases, visit [GitHub Releases](https://github.com/bmad-code-org/BMAD-METHOD/releases/latest).
+
+          ## Usage
+
+          Copy raw markdown URLs for use in AI platforms:
+
+          - Claude Code: `https://raw.githubusercontent.com/bmad-code-org/bmad-bundles/main/claude-code/sub-agents/{agent}.md`
+          - ChatGPT: `https://raw.githubusercontent.com/bmad-code-org/bmad-bundles/main/chatgpt/sub-agents/{agent}.md`
+          - Gemini: `https://raw.githubusercontent.com/bmad-code-org/bmad-bundles/main/gemini/sub-agents/{agent}.md`
+
+          ## Browse
+
+          Visit [https://bmad-code-org.github.io/bmad-bundles/](https://bmad-code-org.github.io/bmad-bundles/) to browse bundles.
+
+          ## Installation (Recommended)
+
+          For full IDE integration:
+          ```bash
+          npx bmad-method@alpha install
+          ```
+
+          ---
+
+          Auto-updated by [BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD) on every main branch merge.
+          EOF
+
+      - name: Commit and push to bmad-bundles
+        run: |
+          cd bmad-bundles
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          git add .
+
+          if git diff --staged --quiet; then
+            echo "No changes to bundles, skipping commit"
+          else
+            COMMIT_SHA=$(cd .. && git rev-parse --short HEAD)
+            git commit -m "Update bundles from BMAD-METHOD@${COMMIT_SHA}"
+            git push
+            echo "✅ Bundles published to GitHub Pages"
+          fi
+
+      - name: Summary
+        run: |
+          echo "## 🎉 Bundles Published!" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Latest bundles** available at:" >> $GITHUB_STEP_SUMMARY
+          echo "- 🌐 Browse: https://bmad-code-org.github.io/bmad-bundles/" >> $GITHUB_STEP_SUMMARY
+          echo "- 📦 Raw files: https://github.com/bmad-code-org/bmad-bundles" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Commit**: ${{ github.sha }}" >> $GITHUB_STEP_SUMMARY
--- a/.github/workflows/manual-release.yaml
+++ b/.github/workflows/manual-release.yaml
@ -61,8 +61,52 @@ jobs:
        run: |
          sed -i 's/"version": ".*"/"version": "${{ steps.version.outputs.new_version }}"/' tools/installer/package.json

-      - name: Build project
-        run: npm run build
+      - name: Generate web bundles
+        run: npm run bundle
+
+      - name: Package bundles for release
+        run: |
+          mkdir -p dist/release-bundles
+
+          # Create staging directory for each platform
+          mkdir -p dist/staging/{claude-code,chatgpt,gemini}
+
+          # Collect all modules per platform
+          cp -r src/modules/bmm/sub-modules/claude-code/* dist/staging/claude-code/ 2>/dev/null || true
+          cp -r src/modules/bmb/sub-modules/claude-code/* dist/staging/claude-code/ 2>/dev/null || true
+          cp -r src/modules/cis/sub-modules/claude-code/* dist/staging/claude-code/ 2>/dev/null || true
+
+          cp -r src/modules/bmm/sub-modules/chatgpt/* dist/staging/chatgpt/ 2>/dev/null || true
+          cp -r src/modules/bmb/sub-modules/chatgpt/* dist/staging/chatgpt/ 2>/dev/null || true
+          cp -r src/modules/cis/sub-modules/chatgpt/* dist/staging/chatgpt/ 2>/dev/null || true
+
+          cp -r src/modules/bmm/sub-modules/gemini/* dist/staging/gemini/ 2>/dev/null || true
+          cp -r src/modules/bmb/sub-modules/gemini/* dist/staging/gemini/ 2>/dev/null || true
+          cp -r src/modules/cis/sub-modules/gemini/* dist/staging/gemini/ 2>/dev/null || true
+
+          # Verify bundles were copied (fail if completely empty)
+          for platform in claude-code chatgpt gemini; do
+            if [ ! "$(ls -A dist/staging/$platform)" ]; then
+              echo "❌ ERROR: No bundles found for $platform"
+              echo "This likely means 'npm run bundle' failed or bundles weren't generated"
+              exit 1
+            fi
+            echo "✅ $platform: $(find dist/staging/$platform -name '*.md' | wc -l) bundles"
+          done
+
+          # Create platform-specific archives
+          tar -czf dist/release-bundles/bmad-bundles-claude-code-v${{ steps.version.outputs.new_version }}.tar.gz \
+            -C dist/staging/claude-code .
+
+          tar -czf dist/release-bundles/bmad-bundles-chatgpt-v${{ steps.version.outputs.new_version }}.tar.gz \
+            -C dist/staging/chatgpt .
+
+          tar -czf dist/release-bundles/bmad-bundles-gemini-v${{ steps.version.outputs.new_version }}.tar.gz \
+            -C dist/staging/gemini .
+
+          # Create all-platforms archive
+          tar -czf dist/release-bundles/bmad-bundles-all-v${{ steps.version.outputs.new_version }}.tar.gz \
+            -C dist/staging .

      - name: Commit version bump
        run: |
@ -151,23 +195,39 @@ jobs:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: npm publish

-      - name: Create GitHub Release
-        uses: actions/create-release@v1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Create GitHub Release with Bundles
+        uses: softprops/action-gh-release@v2
        with:
          tag_name: v${{ steps.version.outputs.new_version }}
-          release_name: "BMad Method v${{ steps.version.outputs.new_version }}"
-          body: ${{ steps.release_notes.outputs.RELEASE_NOTES }}
+          name: "BMad Method v${{ steps.version.outputs.new_version }}"
+          body: |
+            ${{ steps.release_notes.outputs.RELEASE_NOTES }}
+
+            ## 📦 Web Bundles
+
+            Download platform-specific bundles for use in AI platforms:
+
+            - `bmad-bundles-claude-code-v${{ steps.version.outputs.new_version }}.tar.gz` - Claude Code / Claude Projects
+            - `bmad-bundles-chatgpt-v${{ steps.version.outputs.new_version }}.tar.gz` - ChatGPT Custom Instructions
+            - `bmad-bundles-gemini-v${{ steps.version.outputs.new_version }}.tar.gz` - Gemini Gems
+            - `bmad-bundles-all-v${{ steps.version.outputs.new_version }}.tar.gz` - All platforms
+
+            **Latest bundles** (bleeding edge): https://bmad-code-org.github.io/bmad-bundles/
          draft: false
-          prerelease: false
+          prerelease: ${{ contains(steps.version.outputs.new_version, 'alpha') || contains(steps.version.outputs.new_version, 'beta') }}
+          files: |
+            dist/release-bundles/*.tar.gz

      - name: Summary
        run: |
-          echo "🎉 Successfully released v${{ steps.version.outputs.new_version }}!"
-          echo "📦 Published to NPM with @latest tag"
-          echo "🏷️ Git tag: v${{ steps.version.outputs.new_version }}"
-          echo "✅ Users running 'npx bmad-method install' will now get version ${{ steps.version.outputs.new_version }}"
-          echo ""
-          echo "📝 Release notes preview:"
-          cat release_notes.md
+          echo "## 🎉 Successfully released v${{ steps.version.outputs.new_version }}!" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### 📦 Distribution" >> $GITHUB_STEP_SUMMARY
+          echo "- **NPM**: Published with @latest tag" >> $GITHUB_STEP_SUMMARY
+          echo "- **GitHub Release**: https://github.com/bmad-code-org/BMAD-METHOD/releases/tag/v${{ steps.version.outputs.new_version }}" >> $GITHUB_STEP_SUMMARY
+          echo "- **Web Bundles**: Attached to GitHub Release (4 archives)" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### ✅ Installation" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`bash" >> $GITHUB_STEP_SUMMARY
+          echo "npx bmad-method@${{ steps.version.outputs.new_version }} install" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
--- a/.gitignore
+++ b/.gitignore
@ -54,9 +54,15 @@ flattened-codebase.xml
 #UAT template testing output files
 tools/template-test-generator/test-scenarios/

-# Bundler temporary files
+# Bundler temporary files and generated bundles
 .bundler-temp/

+# Generated web bundles (built by CI, not committed)
+src/modules/bmm/sub-modules/
+src/modules/bmb/sub-modules/
+src/modules/cis/sub-modules/
+src/modules/bmgd/sub-modules/
+
 # Test Install Output

 z*/.claude/settings.local.json
--- a/README.md
+++ b/README.md
@ -233,6 +233,8 @@ your-project/
 2. Run `*workflow-init` to set up your project workflow path
 3. Follow the [Quick Start](#-quick-start) guide above to choose your planning track

+**Alternative:** [**Web Bundles**](./docs/USING_WEB_BUNDLES.md) - Use BMAD agents in Claude Projects, ChatGPT, or Gemini without installation
+
 ---

 ## 🎯 Working with Agents & Commands
--- a/docs/BUNDLE_DISTRIBUTION_SETUP.md
+++ b/docs/BUNDLE_DISTRIBUTION_SETUP.md
@ -0,0 +1,95 @@
+# Bundle Distribution Setup (For Maintainers)
+
+**Audience:** BMAD maintainers setting up bundle auto-publishing
+
+---
+
+## One-Time Setup
+
+Run these commands once to enable auto-publishing:
+
+```bash
+# 1. Create bmad-bundles repo
+gh repo create bmad-code-org/bmad-bundles --public --description "BMAD Web Bundles"
+
+# 2. Ensure `main` exists (GitHub Pages API requires a source branch)
+git clone git@github.com:bmad-code-org/bmad-bundles.git
+cd bmad-bundles
+printf '# bmad-bundles\n\nStatic bundles published from BMAD-METHOD.\n' > README.md
+git add README.md
+git commit -m "Initial commit"
+git push origin main
+cd -
+
+# 3. Enable GitHub Pages (API replacement for removed --enable-pages flag)
+gh api repos/bmad-code-org/bmad-bundles/pages --method POST -f source[branch]=main -f source[path]=/
+# (Optional) confirm status
+gh api repos/bmad-code-org/bmad-bundles/pages --jq '{status,source}'
+
+# 4. Create GitHub PAT and add as secret
+# Go to: https://github.com/settings/tokens/new
+# Scopes: repo (full control)
+# Name: bmad-bundles-ci
+# Then add as secret:
+gh secret set BUNDLES_PAT --repo bmad-code-org/BMAD-METHOD
+# (paste PAT when prompted)
+```
+
+If the Pages POST returns `409`, the site already exists. If it returns `422` about `main` missing, redo step 2 to push the initial commit.
+
+**Done.** Bundles auto-publish on every main merge.
+
+---
+
+## How It Works
+
+**On main merge:**
+
+- `.github/workflows/bundle-latest.yaml` runs
+- Publishes to: `https://bmad-code-org.github.io/bmad-bundles/`
+
+**On release:**
+
+- `npm run release:patch` runs `.github/workflows/manual-release.yaml`
+- Attaches bundles to: `https://github.com/bmad-code-org/BMAD-METHOD/releases/latest`
+
+---
+
+## Testing
+
+```bash
+# Test latest channel
+git push origin main
+# Wait 2 min, then: curl https://bmad-code-org.github.io/bmad-bundles/
+
+# Test stable channel
+npm run release:patch
+# Check: gh release view
+```
+
+---
+
+## Troubleshooting
+
+**"Permission denied" or auth errors**
+
+```bash
+# Verify PAT secret exists
+gh secret list --repo bmad-code-org/BMAD-METHOD | grep BUNDLES_PAT
+
+# If missing, recreate PAT and add secret:
+gh secret set BUNDLES_PAT --repo bmad-code-org/BMAD-METHOD
+```
+
+**GitHub Pages not updating / need to re-check config**
+
+```bash
+gh api repos/bmad-code-org/bmad-bundles/pages --jq '{status,source,html_url}'
+```
+
+---
+
+## Distribution URLs
+
+**Stable:** `https://github.com/bmad-code-org/BMAD-METHOD/releases/latest`
+**Latest:** `https://bmad-code-org.github.io/bmad-bundles/`
--- a/docs/USING_WEB_BUNDLES.md
+++ b/docs/USING_WEB_BUNDLES.md
@ -0,0 +1,88 @@
+# Using BMAD Web Bundles (For Users)
+
+**Audience:** Users wanting to use BMAD agents in Claude Projects, ChatGPT, or Gemini
+
+---
+
+## Quick Start
+
+**1. Pick your channel:**
+
+- **Stable:** `https://github.com/bmad-code-org/BMAD-METHOD/releases/latest`
+- **Latest:** `https://bmad-code-org.github.io/bmad-bundles/`
+
+**2. Copy raw markdown URL:**
+
+```
+https://raw.githubusercontent.com/bmad-code-org/bmad-bundles/main/claude-code/sub-agents/bmm-agent-pm.md
+```
+
+**3. Add to AI platform:**
+
+- **Claude Projects:** Project Knowledge → Add URL
+- **ChatGPT:** Custom Instructions → Paste content
+- **Gemini Gems:** Knowledge → Add URL
+
+---
+
+## Available Agents
+
+### Claude Code
+
+- [PM](https://raw.githubusercontent.com/bmad-code-org/bmad-bundles/main/claude-code/sub-agents/bmm-agent-pm.md) | [Architect](https://raw.githubusercontent.com/bmad-code-org/bmad-bundles/main/claude-code/sub-agents/bmm-agent-architect.md) | [TEA](https://raw.githubusercontent.com/bmad-code-org/bmad-bundles/main/claude-code/sub-agents/bmm-agent-tea.md) | [Developer](https://raw.githubusercontent.com/bmad-code-org/bmad-bundles/main/claude-code/sub-agents/bmm-agent-dev.md)
+- [All Agents](https://github.com/bmad-code-org/bmad-bundles/tree/main/claude-code/sub-agents)
+
+### ChatGPT / Gemini
+
+- [Browse ChatGPT](https://github.com/bmad-code-org/bmad-bundles/tree/main/chatgpt/sub-agents)
+- [Browse Gemini](https://github.com/bmad-code-org/bmad-bundles/tree/main/gemini/sub-agents)
+
+---
+
+## Stable vs Latest
+
+**Stable (GitHub Releases):**
+
+- Production-ready, tested releases
+- Version-pinned (v6.0.0, etc.)
+- Download: `https://github.com/bmad-code-org/BMAD-METHOD/releases/latest`
+
+**Latest (GitHub Pages):**
+
+- Bleeding edge (main branch)
+- Auto-updated on every merge
+- Browse: `https://bmad-code-org.github.io/bmad-bundles/`
+
+---
+
+## Full Installation (Recommended)
+
+For IDE integration with slash commands:
+
+```bash
+npx bmad-method@alpha install
+```
+
+Gives you:
+
+- Slash commands (`/bmad:bmm:workflows:prd`)
+- 34+ workflows (not just agents)
+- Status tracking (workflow-status.yaml)
+- Local customization
+
+---
+
+## Troubleshooting
+
+**ChatGPT: "File too large"**
+→ Use stable release (compressed) or report issue
+
+**Bundle not loading**
+→ Use raw URL (not GitHub UI link)
+
+**Out of date**
+→ Wait 2-3 min after main merge, then refresh
+
+---
+
+**Issues?** Report at https://github.com/bmad-code-org/BMAD-METHOD/issues
--- a/docs/index.md
+++ b/docs/index.md
@ -29,6 +29,8 @@ Complete map of all BMad Method v6 documentation with recommended reading paths.

 - **[v4 to v6 Upgrade Guide](./v4-to-v6-upgrade.md)** - Migration path for v4 users
 - **[Document Sharding Guide](./document-sharding-guide.md)** - Split large documents for 90%+ token savings
+- **[Web Bundles](./USING_WEB_BUNDLES.md)** - Use BMAD agents in Claude Projects, ChatGPT, or Gemini without installation
+- **[Bundle Distribution Setup](./BUNDLE_DISTRIBUTION_SETUP.md)** - Maintainer guide for bundle auto-publishing

 ---