@devilsdev/rag-pipeline-utils 2.1.3 → 2.1.5

package/.github/PROJECT_ROADMAP.md

@@ -0,0 +1,102 @@
+# 🛣️ Project Roadmap - RAG Pipeline Utils
+
+> Version: 1.2.0  
+> Status: In Progress  
+> Last Updated: 2025-04-22
+
+This roadmap guides the feature evolution, developer tooling, CI/CD automation, and community integration for the `@devilsdev/rag-pipeline-utils` project. Changes here are synchronized to GitHub Issues and CI workflows.
+
+---
+
+## ✅ Legend
+
+| Symbol | Meaning |
+|--------|---------|
+| ✅     | Done    |
+| 🚧     | In Progress |
+| 🔜     | Upcoming |
+| 🧪     | Experimental |
+
+---
+
+## 📦 Phase 1: Foundation & CI/CD
+
+| Feature | Status | Target Version | Tags |
+|---------|--------|----------------|------|
+| Automated test coverage with Jest | ✅ Done | v2.0.0 | test, ci |
+| Codecov integration + badge | ✅ Done | v2.0.0 | ci, badge |
+| GitHub Actions CI: lint, test, release | ✅ Done | v2.0.0 | ci |
+| GitHub Pages deploy for Docusaurus | ✅ Done | v2.0.0 | docs, deploy |
+| CHANGELOG auto-generation | ✅ Done | v2.0.0 | release |
+| Blog post sync from changelog | ✅ Done | v2.1.0 | blog, release |
+
+---
+
+## 🚀 Phase 2: Community & Docs
+
+| Feature | Status | Target Version | Tags |
+|---------|--------|----------------|------|
+| Interactive onboarding via CLI | 🚧 In Progress | v2.2.0 | devx, onboarding |
+| GitHub Discussions integration | 🔜 | v2.2.0 | community |
+| Contributor guide & issue templates | ✅ Done | v2.0.0 | community, docs |
+| Roadmap → GitHub Issues sync | ✅ Done | v2.1.0 | ci, roadmap |
+| Label sync from roadmap | ✅ Done | v2.1.0 | ci, labels |
+| Manual & automated blog generation | ✅ Done | v2.1.1 | blog, release |
+
+---
+
+## 🧠 Phase 3: Developer Tooling
+
+| Feature | Status | Target Version | Tags |
+|---------|--------|----------------|------|
+| CLI for `release:tag` with changelog preview | ✅ Done | v2.1.1 | cli, release |
+| Hydra.js integration for dynamic RAG config | 🚧 In Progress | v2.2.0 | config, hydra |
+| CLI for roadmap issue tagging | ✅ Done | v2.1.1 | cli, roadmap |
+| Status badge: Release Review Passed | ✅ Done | v2.1.1 | badge, ci |
+| Kanban sync for roadmap issues | ✅ Done | v2.1.1 | roadmap, ci |
+| Custom VS Code snippets & workspace | 🔜 | v2.3.0 | devx |
+
+---
+
+## 🌐 Phase 4: International & Advanced UX
+
+| Feature | Status | Target Version | Tags |
+|---------|--------|----------------|------|
+| Blog subscribe + RSS | ✅ Done | v2.1.1 | blog |
+| i18n translation support | 🔜 | v2.3.0 | i18n |
+| SEO optimization + open graph cards | ✅ Done | v2.1.1 | seo, meta |
+| Comment system on blog posts | 🔜 | v2.3.0 | blog, community |
+| Performance tuning + SSR check | ✅ Done | v2.1.0 | perf, ssr |
+| Multilingual toggle in header | 🔜 | v2.3.0 | i18n, ui |
+
+---
+
+## 🧩 Future Enhancements
+
+| Feature | Status | Target Version | Tags |
+|---------|--------|----------------|------|
+| Plugin support via CLI | 🔜 | v2.4.0 | cli, plugin |
+| Graph-based pipeline UI | 🔜 | v2.5.0 | ux, devx |
+| Real-world RAG examples + use cases | 🔜 | v2.3.0 | docs, showcase |
+| Prebuilt Docker image | 🔜 | v2.4.0 | infra, deploy |
+| Slack/Discord webhook for releases | 🔜 | v2.3.0 | infra, notify |
+
+---
+
+## 📊 Contributor Stats
+
+- GitHub Insights Badge: ![Contributors](https://img.shields.io/github/contributors/DevilsDev/rag-pipeline-utils)
+- Roadmap Sync: `scripts/create-roadmap-issues.js`
+- Label Sync: `scripts/ensure-roadmap-labels.js`
+- CLI Integration: `scripts/release-changelog.js`, `scripts/sync-roadmap-cli.js`
+
+---
+
+## 📁 Files
+
+- `.github/PROJECT_ROADMAP.md` ← source
+- `scripts/ensure-roadmap-labels.js` ← label sync
+- `scripts/create-roadmap-issues.js` ← issue sync
+- `scripts/close-roadmap-done.js` ← close done items
+- `.github/workflows/sync-roadmap.yml` ← automation trigger
+

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,8 @@
+## ✅ Release Quality Checklist
+
+- [ ] CHANGELOG.md updated
+- [ ] Blog post generated (`docs-site/blog/*release*.md`)
+- [ ] `release:tag` and `release:sync` flows tested
+
+<!-- CI Badge -->
+![Release Review Passed](https://github.com/DevilsDev/rag-pipeline-utils/actions/workflows/enforce-release-review.yml/badge.svg)

package/.github/workflows/changelog-auto-commit.yml

@@ -0,0 +1,37 @@
+# Version: 1.0.0
+# Description: Auto-commits CHANGELOG updates generated by tag-release CLI
+# Author: Ali Kahwaji
+
+name: 📘 Sync Changelog from CLI Tags
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  commit-changelog:
+    runs-on: ubuntu-latest
+    steps:
+      - name: ⬇️ Checkout repo
+        uses: actions/checkout@v4
+
+      - name: 🧰 Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: 📦 Install
+        run: npm ci
+
+      - name: 📝 Append Changelog Entry
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/v}
+          node scripts/tag-release.js $VERSION
+          cat scripts/.cache/v$VERSION.log >> CHANGELOG.md
+
+      - name: 🔐 Commit changelog
+        uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          commit_message: "docs(changelog): update for v${{ github.ref_name }}"
+          file_pattern: "CHANGELOG.md"

package/.github/workflows/docs-ci.yml

@@ -1,3 +1,8 @@
+# .github/workflows/docs-ci.yml
+# Version: 1.1.0
+# Description: CI pipeline for linting, testing, and building docs
+# Author: Ali Kahwaji
+
 name: Docs CI
 
 on:
@@ -7,11 +12,8 @@ on:
     branches: [main]
 
 jobs:
-  build-docs:
+  build:
     runs-on: ubuntu-latest
-    defaults:
-      run:
-        working-directory: docs-site
 
     steps:
       - name: ⬇️ Checkout repository
@@ -22,16 +24,23 @@ jobs:
         with:
           node-version: '18'
           cache: 'npm'
-          cache-dependency-path: '**/package-lock.json'
+          cache-dependency-path: 'package-lock.json'
 
       - name: 📦 Install dependencies
         run: npm ci
 
-      - name: 🏗️ Build docs
+      - name: 🧹 Lint codebase
+        run: npm run lint
+
+      - name: 🛠 Build documentation
         run: npm run docs:build
 
-      - name: 🚀 Deploy to GitHub Pages (or similar)
-        uses: peaceiris/actions-gh-pages@v4
+      - name: ✅ Run tests (optional)
+        run: npm test
+        if: ${{ always() }}
+
+      - name: 📦 Upload docs build (optional)
+        uses: actions/upload-artifact@v4
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./docs-site/build
+          name: docusaurus-build
+          path: docs-site/build

package/.github/workflows/docs-deploy.yml

@@ -1,35 +1,55 @@
-name: Deploy Documentation to GitHub Pages
+# .github/workflows/docs-deploy.yml
+# Version: 1.1.0
+# Description: Deploys Docusaurus docs site to GitHub Pages
+# Author: Ali Kahwaji
+
+name: 📚 Deploy Docusaurus Docs
 
 on:
   push:
     branches: [main]
-  pull_request:
-    branches: [main]
+    paths:
+      - 'docs-site/**'
+      - 'docs/**'
+      - 'blog/**'
+      - 'sidebars.js'
+      - 'docusaurus.config.js'
+      - 'package.json'
+
+permissions:
+  contents: write  # Required for GitHub Pages deployment
 
 jobs:
   deploy:
+    name: Deploy to GitHub Pages
     runs-on: ubuntu-latest
-    defaults:
-      run:
-        working-directory: docs-site
 
     steps:
-      - name: ⬇️ Checkout repository
+      - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: 🟢 Setup Node.js
+      - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
           node-version: '18'
+          cache: 'npm'
 
-      - name: 📦 Install dependencies
+      - name: Install dependencies
         run: npm ci
 
-      - name: 🏗️ Build docs
+      - name: Build docs
         run: npm run docs:build
 
-      - name: 🚀 Deploy to GitHub Pages
+      - name: Configure Git user
+        run: |
+          git config --global user.name "GitHub Actions"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Deploy to GitHub Pages
         uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./docs-site/build
+          publish_dir: docs-site/build
+          publish_branch: gh-pages
+          user_name: github-actions[bot]
+          user_email: github-actions[bot]@users.noreply.github.com

package/.github/workflows/enforce-release-review.yml

@@ -0,0 +1,47 @@
+# .github/workflows/enforce-release-review.yml
+# Version: 1.0.1
+# Description: Prevents merge if changelog/blog updates not reviewed. Supports badge + manual trigger.
+# Author: Ali Kahwaji
+
+name: 🛡 Release Review Enforcement
+
+on:
+  pull_request:
+    branches: [main]
+  workflow_dispatch:  # ✅ Manual trigger from Actions tab
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  review-check:
+    name: Validate Changelog & Blog Updates
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: 📥 Checkout repo
+        uses: actions/checkout@v4
+
+      - name: 🔍 Scan for changelog/blog edits
+        id: check
+        run: |
+          git fetch origin main --depth=1
+          CHANGED_FILES=$(git diff --name-only origin/main...HEAD)
+
+          echo "Changed files:"
+          echo "$CHANGED_FILES"
+
+          if echo "$CHANGED_FILES" | grep -qE 'CHANGELOG\.md|docs-site/blog/'; then
+            echo "✅ Changelog or blog post updated."
+            echo "result=pass" >> "$GITHUB_OUTPUT"
+          else
+            echo "❌ No changelog or blog edits found."
+            echo "result=fail" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: 🚫 Fail if missing changelog or blog updates
+        if: steps.check.outputs.result == 'fail'
+        run: |
+          echo "Missing required changelog or blog post for release."
+          exit 1

package/.github/workflows/release-sync.yml

@@ -0,0 +1,50 @@
+# .github/workflows/release-sync.yml
+# Version: 1.0.0
+# Description: Syncs changelog/tag to blog post
+# Author: Ali Kahwaji
+
+name: 🔄 Release Sync
+
+on:
+  push:
+    tags:
+      - 'v*' # any pushed Git tag
+    paths:
+      - 'CHANGELOG.md'
+      - 'scripts/**'
+      - '.github/workflows/release-sync.yml'
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  publish-release-blog:
+    name: 📝 Create Blog Post from CHANGELOG + Tag
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: 🧾 Checkout Repo
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # get full commit history for changelog diff
+
+      - name: 🧰 Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: 📦 Install deps
+        run: npm ci
+
+      - name: 🔁 Generate blog post
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/}
+          PREV=$(git tag --sort=committerdate | grep -B1 $VERSION | head -n1)
+          node scripts/generate-release-note.js $VERSION $PREV
+
+      - name: 💬 Commit release blog
+        uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          commit_message: "docs(blog): auto-publish release notes for ${{ github.ref_name }}"
+          file_pattern: "docs-site/blog/*.md"

package/.github/workflows/roadmap-label-sync.yml

@@ -0,0 +1,35 @@
+name: 🔖 Sync Roadmap Labels
+
+on:
+  push:
+    paths:
+      - '.github/roadmap-labels.yml'
+      - 'scripts/sync-roadmap-labels.js'
+  workflow_dispatch:
+
+permissions:
+  issues: write
+  contents: read
+
+jobs:
+  sync-labels:
+    runs-on: ubuntu-latest
+    name: Sync Labels from Roadmap Config
+
+    steps:
+      - name: 📥 Checkout repo
+        uses: actions/checkout@v4
+
+      - name: 🛠 Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: 📦 Install dependencies
+        run: npm ci
+
+      - name: 🔖 Run label sync script
+        run: node scripts/sync-roadmap-labels.js
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.github/workflows/roadmap-labels.yml

@@ -0,0 +1,67 @@
+# Version: 1.0.0
+# Description: Ensures roadmap labels (priority, group) exist in the repo
+# Author: Ali Kahwaji
+
+name: 🔖 Sync Roadmap Labels
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - '.github/workflows/roadmap-labels.yml'
+
+jobs:
+  sync-labels:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: ⬇️ Checkout repository
+        uses: actions/checkout@v4
+
+      - name: 🟢 Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: 📦 Install octokit
+        run: npm install octokit
+
+      - name: 🔖 Run label sync
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_REPO: ${{ github.repository }}
+        run: |
+          node <<EOF
+          const { Octokit } = require("octokit");
+
+          const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });
+          const [owner, repo] = process.env.GITHUB_REPO.split("/");
+
+          const labels = [
+            { name: "priority: high", color: "e11d48", description: "High priority roadmap item" },
+            { name: "priority: medium", color: "f59e0b", description: "Medium priority roadmap item" },
+            { name: "priority: low", color: "10b981", description: "Low priority roadmap item" },
+            { name: "group: docs", color: "6366f1", description: "Documentation features" },
+            { name: "group: devx", color: "06b6d4", description: "Developer experience improvements" },
+            { name: "group: community", color: "ec4899", description: "Community tools & engagement" },
+            { name: "group: blog", color: "f97316", description: "Blog & SEO enhancements" },
+            { name: "group: infra", color: "64748b", description: "Infrastructure & deployment features" }
+          ];
+
+          (async () => {
+            const existing = await octokit.rest.issues.listLabelsForRepo({ owner, repo });
+            const existingNames = new Set(existing.data.map(l => l.name));
+
+            for (const label of labels) {
+              if (!existingNames.has(label.name)) {
+                console.log(`➕ Creating label: ${label.name}`);
+                await octokit.rest.issues.createLabel({ owner, repo, ...label });
+              } else {
+                console.log(`✅ Label already exists: ${label.name}`);
+              }
+            }
+          })().catch(err => {
+            console.error("Label sync failed:", err);
+            process.exit(1);
+          });
+          EOF

package/.github/workflows/roadmap-sync.yml

@@ -0,0 +1,44 @@
+name: 🚀 Roadmap Sync (Labels + Issues)
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - '.github/roadmap-labels.yml'
+      - '.github/PROJECT_ROADMAP.md'
+      - 'scripts/create-roadmap-issues.js'
+      - 'scripts/ensure-roadmap-labels.js'
+
+  workflow_dispatch:
+
+permissions:
+  issues: write
+  contents: read
+
+jobs:
+  roadmap-sync:
+    name: 🔁 Sync Labels + Issues from Roadmap
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: 📥 Checkout repository
+        uses: actions/checkout@v4
+
+      - name: 🛠 Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: 📦 Install dependencies
+        run: npm ci
+
+      - name: 🔖 Sync GitHub labels from roadmap-labels.yml
+        run: node scripts/ensure-roadmap-labels.js
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: 📝 Create or update roadmap issues
+        run: node scripts/create-roadmap-issues.js
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.github/workflows/sync-roadmap.yml

@@ -0,0 +1,62 @@
+# .github/workflows/sync-roadmap.yml
+# Version: 2.1.0
+# Description: Unified workflow to sync roadmap issues, labels, and states
+# Author: Ali Kahwaji
+
+name: 🚀 Sync Roadmap to GitHub Issues
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - '.github/PROJECT_ROADMAP.md'
+      - '.github/workflows/sync-roadmap.yml'
+      - 'scripts/**.js'
+
+permissions:
+  contents: write
+  issues: write
+
+jobs:
+  sync:
+    name: 📌 Roadmap Sync
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: ⬇️ Checkout
+        uses: actions/checkout@v4
+
+      - name: 🛠 Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: 📦 Install roadmap dependencies
+        run: npm install
+        env:
+          NODE_ENV: development
+
+      - name: 🔖 Ensure roadmap labels exist
+        run: node scripts/ensure-roadmap-labels.js
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_REPO: ${{ github.repository }}
+
+      - name: 🗂 Sync roadmap issues
+        run: node scripts/create-roadmap-issues.js
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_REPO: ${{ github.repository }}
+
+      - name: 🏷 Apply labels to roadmap issues
+        run: node scripts/label-roadmap-issues.js
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_REPO: ${{ github.repository }}
+
+      - name: ✅ Close completed issues
+        run: node scripts/close-done-roadmap-issues.js
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_REPO: ${{ github.repository }}

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [2.1.5](https://github.com/DevilsDev/rag-pipeline-utils/compare/v2.1.4...v2.1.5) (2025-04-22)
+
+
+### Bug Fixes
+
+* **scripts:** prevent null status crash in roadmap issue closer ([89d5a0b](https://github.com/DevilsDev/rag-pipeline-utils/commit/89d5a0bc4cac554975974558b97974297816f169))
+
+## [2.1.4](https://github.com/DevilsDev/rag-pipeline-utils/compare/v2.1.3...v2.1.4) (2025-04-21)
+
+
+### Bug Fixes
+
+* update CI and deployment workflows for docs build and GitHub Pages deployment ([11739ba](https://github.com/DevilsDev/rag-pipeline-utils/commit/11739ba222669e359232807e461bc84d68d913cb))
+* update CI and deployment workflows for docs build and GitHub Pages deployment ([8de276f](https://github.com/DevilsDev/rag-pipeline-utils/commit/8de276f8cb6c91a291322783dc944b0f4799974f))
+
 ## [2.1.3](https://github.com/DevilsDev/rag-pipeline-utils/compare/v2.1.2...v2.1.3) (2025-04-21)
 
 

package/README.md

@@ -10,6 +10,9 @@
 [![codecov](https://codecov.io/gh/DevilsDev/rag-pipeline-utils/branch/main/graph/badge.svg)](https://codecov.io/gh/DevilsDev/rag-pipeline-utils)
 ![Release](https://img.shields.io/github/v/release/DevilsDev/rag-pipeline-utils?label=release)
 ![License](https://img.shields.io/github/license/devilsdev/rag-pipeline-utils)
+![Release Review Passed](https://github.com/DevilsDev/rag-pipeline-utils/actions/workflows/enforce-release-review.yml/badge.svg?branch=main)
+
+
 
 ## Description
 
@@ -136,6 +139,36 @@ We welcome contributions via PRs, especially new mock providers, validation help
 
 
 
+## Contributors Guide
+
+For active maintainers and collaborators:
+
+- **Roadmap & Feature Planning**  
+  See [.github/PROJECT_ROADMAP.md](.github/PROJECT_ROADMAP.md) for the implementation phases, priorities, and tracking tags for all major developer-facing features.
+
+- **Milestone Tags**
+  | Tag         | Description                        |
+  |-------------|------------------------------------|
+  | `phase-1`   | Foundation – testing, CI, tutorials |
+  | `phase-2`   | Community, blog, discussions       |
+  | `phase-3`   | CLI, VS Code tools, theming        |
+  | `phase-4`   | i18n, integrations, case studies   |
+
+_Note: This file is not included in public documentation builds._
+
+
+## Manual Test Checklist
+
+For full validation of roadmap sync, changelog automation, CI/CD, and blog generation:
+
+➡️ [View Manual Test Checklist](scripts/manual-test-checklist.md)
+
+## Manual CI Rollout
+
+git commit --allow-empty -m "ci(test): trigger all CI workflows"
+git push origin main
+
+
 ## License
 
 This project is licensed under the **GNU GPL v3.0** License - see the [LICENSE](./LICENSE) file for details.