@devilsdev/rag-pipeline-utils 2.1.4 → 2.1.7

package/scripts/create-roadmap-issues.js

@@ -0,0 +1,47 @@
+// scripts/create-roadmap-issues.js
+
+/**
+ * Version: 2.0.0
+ * Description: Parses PROJECT_ROADMAP.md and syncs GitHub issues
+ * Author: Ali Kahwaji
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { Octokit } from 'octokit';
+import yaml from 'js-yaml';
+
+const roadmapPath = new URL('../.github/PROJECT_ROADMAP.md', import.meta.url);
+
+export async function createRoadmapIssues({ token, owner, repo }) {
+  const octokit = new Octokit({ auth: token });
+  const content = await fs.readFile(roadmapPath, 'utf-8');
+
+  const blocks = content.split(/^##\s+/gm).slice(1);
+
+  for (const block of blocks) {
+    const [header, ...bodyLines] = block.trim().split('\n');
+    const title = header.trim();
+    const metadata = {};
+    const description = [];
+
+    for (const line of bodyLines) {
+      if (line.includes(':') && line.includes('**')) {
+        const [key, val] = line.split(':');
+        metadata[key.trim()] = val.replace(/\*\*/g, '').trim();
+      } else {
+        description.push(line);
+      }
+    }
+
+    const issue = await octokit.rest.issues.create({
+      owner,
+      repo,
+      title,
+      body: description.join('\n'),
+      labels: [metadata.Priority, metadata.Group].filter(Boolean),
+    });
+
+    console.log(`✅ Created: ${issue.data.title}`);
+  }
+}

package/scripts/ensure-roadmap-labels.js

@@ -0,0 +1,73 @@
+/**
+ * Version: 2.0.1
+ * Path: scripts/ensure-roadmap-labels.js
+ * Description: Ensures consistent GitHub labels for roadmap tracking and automation.
+ * Author: Ali Kahwaji
+ */
+
+import { Octokit } from 'octokit';
+
+
+/**
+ * Label definitions for roadmap tracking.
+ * Modify this array to add or update roadmap labels.
+ * Each object must include: name, color (hex), description.
+ */
+const roadmapLabels = [
+  { 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' },
+  { name: 'group: hydra', color: '9333ea', description: 'Hydra runtime & configuration' },
+  { name: 'status: done', color: '10b981', description: 'Issue has been completed' }
+];
+
+/**
+ * Ensures all roadmap labels are present in the target GitHub repository.
+ * Skips label creation if already present.
+ *
+ * @param {Object} params
+ * @param {string} params.token - GitHub access token
+ * @param {string} params.owner - Repository owner
+ * @param {string} params.repo  - Repository name
+ */
+async function ensureRoadmapLabels({ token, owner, repo }) {
+  const octokit = new Octokit({ auth: token });
+
+  const { data: existingLabels } = await octokit.rest.issues.listLabelsForRepo({
+    owner,
+    repo
+  });
+
+  const existingNames = new Set(existingLabels.map((label) => label.name));
+
+  for (const label of roadmapLabels) {
+    if (!existingNames.has(label.name)) {
+      await octokit.rest.issues.createLabel({ owner, repo, ...label });
+    }
+  }
+}
+
+// CLI support
+if (process.argv[1] === new URL(import.meta.url).pathname) {
+  const [owner, repo] = process.env.GITHUB_REPOSITORY?.split('/') || [];
+  const token = process.env.GITHUB_TOKEN;
+
+  if (!token || !owner || !repo) {
+    console.error('Missing required GITHUB_TOKEN or GITHUB_REPOSITORY');
+    process.exit(1);
+  }
+
+  ensureRoadmapLabels({ token, owner, repo })
+    .then(() => console.log('✅ Roadmap labels ensured'))
+    .catch((err) => {
+      console.error('Label sync failed:', err);
+      process.exit(1);
+    });
+}
+
+export { ensureRoadmapLabels, roadmapLabels };

package/scripts/generate-release-note.js

@@ -1,40 +1,110 @@
-// File: scripts/generate-release-note.js
+// scripts/generate-release-note.js
 /**
- * Version: 1.2.0
- * Description: Injects release metadata into markdown template
+ * Version: 2.3.0
+ * Description: Generate release blog + changelog section, auto-push to Git, fallback to safe defaults
  * Author: Ali Kahwaji
  */
 
-const fs = require('fs');
-const path = require('path');
-const { execSync } = require('child_process');
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+import { fileURLToPath } from 'url';
 
-const [,, version, previousTag] = process.argv;
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
 
-if (!version || !previousTag) {
-  console.error('Usage: node scripts/generate-release-note.js <version> <previousTag>');
+const [, , newVersionArg, previousVersionArg] = process.argv;
+
+if (!newVersionArg) {
+  console.error('❌ Usage: node scripts/generate-release-note.js <new-tag> <previous-tag?>');
+  process.exit(1);
+}
+
+const newVersion = newVersionArg.startsWith('v') ? newVersionArg : `v${newVersionArg}`;
+
+// 🔁 Fallback to previous git tag
+function resolvePreviousTag() {
+  try {
+    const tags = execSync('git tag --sort=-creatordate', { encoding: 'utf-8' })
+      .split('\n')
+      .filter(Boolean);
+    const idx = tags.indexOf(newVersion);
+    return tags[idx + 1] || tags[1] || null;
+  } catch {
+    return null;
+  }
+}
+
+const prevVersion = previousVersionArg || resolvePreviousTag();
+if (!prevVersion) {
+  console.error('❌ Could not resolve previous tag.');
   process.exit(1);
 }
 
-const templatePath = path.join(__dirname, '../.github/release-template.md');
-const outputPath = path.join(__dirname, `../docs-site/blog/${new Date().toISOString().split('T')[0]}-release-${version}.md`);
+// 📦 Get commits between versions
+function getCommits(from, to) {
+  try {
+    return execSync(`git log ${from}..${to} --pretty=format:"- %s"`, { encoding: 'utf-8' });
+  } catch (err) {
+    console.error('❌ Failed to fetch commits:', err.message);
+    process.exit(1);
+  }
+}
+
+function generateChangelogSection(commits) {
+  return `## ${newVersion}\n\n${commits}\n\n---\n`;
+}
 
-const template = fs.readFileSync(templatePath, 'utf-8');
+function generateBlogMarkdown(version, commits) {
+  const date = new Date().toISOString().slice(0, 10);
+  const slug = `release-${version}`;
+  return `---
+slug: ${slug}
+title: "🚀 Version ${version} Released"
+authors: [ali]
+tags: [release, changelog]
+---
 
-// Count contributors
-const contributors = execSync(`git shortlog -sne ${previousTag}..HEAD | wc -l`).toString().trim();
-// Count commits
-const commits = execSync(`git rev-list --count ${previousTag}..HEAD`).toString().trim();
-// ISO date
-const date = new Date().toISOString().split('T')[0];
+RAG Pipeline Utils **${version}** is now available on NPM!
 
-// Inject into template
-const filled = template
-  .replace(/{{VERSION}}/g, version)
-  .replace(/{{PREVIOUS_TAG}}/g, previousTag)
-  .replace(/{{DATE}}/g, date)
-  .replace(/{{CONTRIBUTORS}}/g, contributors)
-  .replace(/{{COMMITS}}/g, commits);
+## 🔧 Changes
+
+${commits}
+
+## 🔗 Resources
+
+- GitHub Compare: [${prevVersion}...${version}](https://github.com/DevilsDev/rag-pipeline-utils/compare/${prevVersion}...${version})
+- View full [CHANGELOG on GitHub](https://github.com/DevilsDev/rag-pipeline-utils/blob/main/CHANGELOG.md)
+`;
+}
+
+const commits = getCommits(prevVersion, newVersion);
+const blogContent = generateBlogMarkdown(newVersion, commits);
+const changelogSection = generateChangelogSection(commits);
+
+// 📍 Paths
+const today = new Date().toISOString().slice(0, 10);
+const blogPath = path.join(__dirname, `../docs-site/blog/${today}-${newVersion}.md`);
+const changelogPath = path.join(__dirname, '../CHANGELOG.md');
+
+// 📝 Write blog + changelog
+fs.writeFileSync(blogPath, blogContent, 'utf-8');
+fs.appendFileSync(changelogPath, `\n${changelogSection}`, 'utf-8');
+
+// 🔐 Commit and push
+try {
+  execSync('git config user.name "github-actions[bot]"');
+  execSync('git config user.email "41898282+github-actions[bot]@users.noreply.github.com"');
+  execSync('git add CHANGELOG.md docs-site/blog/*.md');
+  execSync(`git commit -m "docs(release): publish changelog and blog for ${newVersion}"`);
+  execSync('git push origin main');
+  console.log(`✅ Blog + changelog committed for ${newVersion}`);
+} catch (err) {
+  console.warn('⚠️ Git commit skipped (already committed or no changes).');
+}
 
-fs.writeFileSync(outputPath, filled);
-console.log(`✅ Generated release blog: ${outputPath}`);
+// 📦 Local preview
+console.log('\n📘 Blog Preview:\n');
+console.log(blogContent);
+console.log('\n📘 Changelog Section:\n');
+console.log(changelogSection);

package/scripts/get-previous-tag.js

@@ -0,0 +1,40 @@
+/**
+ * Version: 1.0.0
+ * Description: Helper to find the previous Git semver tag before a given tag
+ * Usage: node scripts/get-previous-tag.js v2.1.5
+ * Output: v2.1.4
+ * Author: Ali Kahwaji
+ */
+
+import { execSync } from 'child_process';
+
+const currentTag = process.argv[2];
+
+if (!currentTag) {
+  console.error('❌ Usage: node get-previous-tag.js <current-tag>');
+  process.exit(1);
+}
+
+try {
+  // Ensure full tag history
+  execSync('git fetch --tags --unshallow 2>/dev/null || git fetch --tags', { stdio: 'inherit' });
+
+  // List all tags sorted by version (most recent last), remove current tag
+  const tags = execSync('git tag --sort=version:refname', { encoding: 'utf-8' })
+    .split('\n')
+    .map(tag => tag.trim())
+    .filter(Boolean);
+
+  const idx = tags.indexOf(currentTag);
+
+  if (idx <= 0) {
+    console.error('⚠️ Could not find previous tag before', currentTag);
+    process.exit(1);
+  }
+
+  const previousTag = tags[idx - 1];
+  console.log(previousTag);
+} catch (err) {
+  console.error('❌ Failed to resolve previous tag:', err.message);
+  process.exit(1);
+}

package/scripts/label-roadmap-issues.js

@@ -0,0 +1,125 @@
+/**
+ * Version: 2.0.0
+ * Description: Auto-label roadmap issues and clean up outdated items
+ * Author: Ali Kahwaji
+ */
+
+import { Octokit } from 'octokit';
+import fs from 'fs/promises';
+import 'dotenv/config';
+
+const repo = process.env.GITHUB_REPO;
+const token = process.env.GITHUB_TOKEN;
+const ROADMAP_FILE = '.github/PROJECT_ROADMAP.md';
+const CLOSE_STALE = true;
+
+if (!repo || !token) {
+  console.error('Missing GITHUB_REPO or GITHUB_TOKEN env vars');
+  process.exit(1);
+}
+
+const [owner, repoName] = repo.split('/');
+const octokit = new Octokit({ auth: token });
+
+const PRIORITY_LABELS = {
+  High: 'priority: high',
+  Medium: 'priority: medium',
+  Low: 'priority: low',
+};
+
+const GROUP_LABELS = {
+  'Documentation': 'group: docs',
+  'Developer Experience': 'group: devx',
+  'Community': 'group: community',
+  'Blog & SEO': 'group: blog',
+  'Infrastructure': 'group: infra',
+};
+
+function parseRoadmapMarkdown(content) {
+  const lines = content.split('\n').filter(l => l.includes('|'));
+  const titles = new Set();
+
+  for (const line of lines) {
+    const parts = line.split('|').map(p => p.trim());
+    if (parts.length < 4 || parts[0] === 'Phase') continue;
+    const title = parts[3];
+    titles.add(title);
+  }
+
+  return titles;
+}
+
+async function run() {
+  const roadmapRaw = await fs.readFile(ROADMAP_FILE, 'utf8');
+  const roadmapTitles = parseRoadmapMarkdown(roadmapRaw);
+
+  const issues = await octokit.paginate(octokit.rest.issues.listForRepo, {
+    owner,
+    repo: repoName,
+    state: 'open',
+    per_page: 100,
+  });
+
+  for (const issue of issues) {
+    if (issue.pull_request) continue;
+
+    const title = issue.title.trim();
+    const body = issue.body || '';
+    const labels = new Set(issue.labels.map(l => typeof l === 'string' ? l : l.name));
+
+    const priority = Object.keys(PRIORITY_LABELS).find(p => body.includes(`Priority: ${p}`));
+    const group = Object.keys(GROUP_LABELS).find(g => body.includes(`Group: ${g}`));
+
+    const expectedLabels = [
+      ...(priority ? [PRIORITY_LABELS[priority]] : []),
+      ...(group ? [GROUP_LABELS[group]] : [])
+    ];
+
+    const currentRoadmap = roadmapTitles.has(title);
+
+    // Update Labels
+    const labelsToAdd = expectedLabels.filter(label => !labels.has(label));
+    const labelsToRemove = [...labels].filter(label =>
+      Object.values(PRIORITY_LABELS).includes(label) ||
+      Object.values(GROUP_LABELS).includes(label)
+    ).filter(label => !expectedLabels.includes(label));
+
+    if (labelsToAdd.length > 0 || labelsToRemove.length > 0) {
+      console.log(`🔁 Updating labels for issue #${issue.number}: ${title}`);
+      if (labelsToAdd.length) {
+        await octokit.rest.issues.addLabels({
+          owner,
+          repo: repoName,
+          issue_number: issue.number,
+          labels: labelsToAdd,
+        });
+      }
+      if (labelsToRemove.length) {
+        for (const label of labelsToRemove) {
+          await octokit.rest.issues.removeLabel({
+            owner,
+            repo: repoName,
+            issue_number: issue.number,
+            name: label,
+          });
+        }
+      }
+    }
+
+    // Optionally Close stale issues
+    if (CLOSE_STALE && !currentRoadmap) {
+      console.log(`🧹 Closing stale issue #${issue.number} (${title}) – not in roadmap`);
+      await octokit.rest.issues.update({
+        owner,
+        repo: repoName,
+        issue_number: issue.number,
+        state: 'closed',
+      });
+    }
+  }
+}
+
+run().catch(err => {
+  console.error('❌ Label script failed:', err);
+  process.exit(1);
+});

package/scripts/manual-test-checklist.md

@@ -0,0 +1,90 @@
+# ✅ Manual Test Checklist for RAG Pipeline Utils
+
+This document outlines manual test points for validating roadmap automation, documentation builds, CI/CD, blog sync, and changelog generation.
+
+---
+
+## 1. 🔄 Roadmap Sync + Label Automation
+
+| ✅ Task | Command or Trigger | Notes |
+|--------|--------------------|-------|
+| Sync `PROJECT_ROADMAP.md` to GitHub Issues | `git push` or `workflow_dispatch` for `sync-roadmap.yml` | Issues, assignees, labels should match |
+| Auto-create missing roadmap labels | `sync-roadmap.yml` step: `ensure-roadmap-labels.js` | Should not error even if labels exist |
+| Label updates reflect correct color & description | Rerun roadmap sync | Existing labels should be updated |
+| Roadmap issue closed on ✅ Done status | Modify `PROJECT_ROADMAP.md` status and sync | Corresponding issue should be auto-closed |
+
+---
+
+## 2. 🧭 CLI + Manual Utilities
+
+| ✅ Task | Command | Notes |
+|--------|---------|-------|
+| Create roadmap issues manually | `node scripts/create-roadmap-issues.js` | Creates GitHub Issues |
+| Ensure labels via CLI | `node scripts/ensure-roadmap-labels.js` | Must succeed with idempotency |
+| Generate changelog and preview | `npm run release:tag` | Prompt for tag + generate CHANGELOG |
+| Preview auto-generated blog post | Preview `.md` file in `/docs-site/blog` before push |
+
+---
+
+## 3. 📚 Docs + Deployment
+
+| ✅ Task | Command | Notes |
+|--------|---------|-------|
+| Build Docusaurus | `npm run docs:build` | No broken links, light/dark theme OK |
+| Deploy to GitHub Pages | `npm run docs:deploy` | Check rendered site at `/rag-pipeline-utils` |
+| Verify CHANGELOG link works | Test `/blog` page post link to `CHANGELOG.md` |
+
+---
+
+## 4. 🧪 CI/CD Validation
+
+| ✅ Task | Check | Notes |
+|--------|-------|-------|
+| CI Lint + Test runs | ✅ `ci.yml` | Lint passes, all Jest tests green |
+| Docs CI runs correctly | ✅ `docs-ci.yml` | No script missing error, build valid |
+| Docs auto-deploys on push | ✅ `docs-deploy.yml` | Publishes to GitHub Pages |
+
+---
+
+## 5. 🏷 GitHub Releases
+
+| ✅ Task | Trigger | Notes |
+|--------|---------|-------|
+| Generate blog post on release | Publish GitHub tag | `publish-release-blog.yml` should commit new `.md` |
+| Auto-fill blog content | From `CHANGELOG.md` and compare link | Author + commit stats populated |
+
+---
+
+## 6. 🛡 Release Gatekeeping & Metadata
+
+| ✅ Task | Outcome | Notes |
+|--------|---------|-------|
+| Badge renders in README | `![Release Review Passed]` | Should point to last workflow run |
+| Protected branch config for PRs | Status check on `release:review` | Prevents push without passing review |
+
+---
+
+## 7. 🧾 Filesystem and Cleanup
+
+| ✅ Task | Notes |
+|--------|-------|
+| `src/stories/` removed | No Storybook assets in GH Pages |
+| `postcss.config.cjs` & `tailwind.config.js` removed | Confirm no broken styling or build errors |
+
+---
+
+## 🔁 Optional Manual Commands
+
+```bash
+# Sync roadmap manually
+node scripts/create-roadmap-issues.js
+
+# Ensure roadmap labels
+node scripts/ensure-roadmap-labels.js
+
+# Trigger changelog + blog post flow
+npm run release:tag
+
+# Build and deploy docs
+npm run docs:build && npm run docs:deploy
+```

package/scripts/sync-labels.js

@@ -0,0 +1,71 @@
+/**
+ * Version: 1.1.0
+ * Description: Syncs GitHub labels based on roadmap-labels.yml; updates existing, creates missing.
+ * Author: Ali Kahwaji
+ */
+
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+import { Octokit } from '@octokit/rest';
+
+const GITHUB_TOKEN = process.env.GITHUB_TOKEN;
+const REPO = process.env.GITHUB_REPOSITORY;
+
+if (!GITHUB_TOKEN || !REPO) {
+  console.error('❌ GITHUB_TOKEN or GITHUB_REPOSITORY not defined in environment.');
+  process.exit(1);
+}
+
+const [owner, repo] = REPO.split('/');
+const octokit = new Octokit({ auth: GITHUB_TOKEN });
+
+const LABELS_FILE = path.join('.github', 'roadmap-labels.yml');
+
+function loadLabelsFromYAML(filePath) {
+  try {
+    const file = fs.readFileSync(filePath, 'utf8');
+    return yaml.load(file);
+  } catch (err) {
+    console.error('❌ Failed to load roadmap-labels.yml:', err);
+    process.exit(1);
+  }
+}
+
+async function syncLabels() {
+  const labels = loadLabelsFromYAML(LABELS_FILE);
+  const existingLabels = await octokit.paginate(octokit.rest.issues.listLabelsForRepo, {
+    owner,
+    repo,
+  });
+
+  for (const label of labels) {
+    const existing = existingLabels.find(l => l.name === label.name);
+
+    try {
+      if (existing) {
+        console.log(`🔁 Updating label: ${label.name}`);
+        await octokit.rest.issues.updateLabel({
+          owner,
+          repo,
+          name: label.name,
+          color: label.color,
+          description: label.description,
+        });
+      } else {
+        console.log(`➕ Creating label: ${label.name}`);
+        await octokit.rest.issues.createLabel({
+          owner,
+          repo,
+          name: label.name,
+          color: label.color,
+          description: label.description,
+        });
+      }
+    } catch (err) {
+      console.error(`❌ Failed to process label: ${label.name}`, err.message);
+    }
+  }
+}
+
+syncLabels();

package/scripts/sync-roadmap-labels.js

@@ -0,0 +1,21 @@
+// scripts/sync-roadmap-labels.js
+
+/**
+ * Version: 1.1.0
+ * Description: Sync roadmap labels and issues
+ * Author: Ali Kahwaji
+ */
+
+import { ensureRoadmapLabels } from './ensure-roadmap-labels.js';
+import { createRoadmapIssues } from './create-roadmap-issues.js';
+
+const [owner, repo] = process.env.GITHUB_REPOSITORY.split('/');
+const token = process.env.GITHUB_TOKEN;
+
+if (!token) {
+  console.error('❌ Missing GITHUB_TOKEN');
+  process.exit(1);
+}
+
+await ensureRoadmapLabels({ token, owner, repo });
+await createRoadmapIssues({ token, owner, repo });

package/scripts/tag-release.js

@@ -0,0 +1,64 @@
+/**
+ * Version: 2.0.0
+ * Description: Tags release, updates changelog, optionally opens blog preview
+ * Author: Ali Kahwaji
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+import readline from 'readline';
+
+const VERSION = process.argv[2];
+const PREVIEW = process.argv.includes('--preview');
+
+if (!VERSION) {
+  console.error('❌ Usage: node release-tag.js <version> [--preview]');
+  process.exit(1);
+}
+
+const tag = `v${VERSION}`;
+const blogPath = path.join('docs-site', 'blog');
+
+// Step 1: Run changelog injection
+execSync(`node scripts/generate-release-note.js ${VERSION}`, { stdio: 'inherit' });
+
+// Step 2: Find generated blog file
+const date = new Date().toISOString().split('T')[0];
+const file = path.join(blogPath, `${date}-release-${tag}.md`);
+
+if (!fs.existsSync(file)) {
+  console.error(`❌ Blog post not generated: ${file}`);
+  process.exit(1);
+}
+
+// Step 3: Preview if enabled
+if (PREVIEW) {
+  const editor = process.env.EDITOR || 'code'; // fallback to VS Code
+  try {
+    execSync(`${editor} ${file}`, { stdio: 'inherit' });
+  } catch (err) {
+    console.warn('⚠️ Failed to open in editor. Please review manually:', file);
+  }
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  rl.question(`✅ Ready to commit and push ${tag}? (y/n): `, (answer) => {
+    rl.close();
+    if (answer.toLowerCase() !== 'y') {
+      console.log('❌ Aborted. No tag pushed.');
+      process.exit(0);
+    }
+    finalizeRelease();
+  });
+} else {
+  finalizeRelease();
+}
+
+// Final tagging + push
+function finalizeRelease() {
+  execSync(`git add CHANGELOG.md ${file}`);
+  execSync(`git commit -m "release: v${VERSION}"`);
+  execSync(`git tag ${tag}`);
+  execSync('git push && git push --tags');
+  console.log(`🎉 Release ${tag} published and blog post staged!`);
+}