chore: upgrade Node.js requirement from 18 to 20

.beads/issues.jsonl

@@ -6,7 +6,7 @@
 {"id":"bluefin-docs-bdg","title":"Investigate .planning directory structure","description":"Check if .planning directory exists and analyze its structure to understand the current work tracking system that needs to be migrated to beads. Need to understand:\n- Directory structure and file organization\n- Issue/task format and metadata\n- Dependency tracking approach\n- Current status of work items\n- Migration strategy to beads","status":"closed","priority":1,"issue_type":"task","owner":"jorge.castro@gmail.com","created_at":"2026-01-31T00:34:48.473828624-05:00","created_by":"Jorge O. Castro","updated_at":"2026-01-31T00:37:59.53986077-05:00","closed_at":"2026-01-31T00:37:59.53986077-05:00","close_reason":"Investigation complete. Found .planning structure with todos, phases, and documentation. All pending todos migrated to beads."}
 {"id":"bluefin-docs-e33","title":"Add Community Engagement section to monthly reports","description":"## Problem\n\nMonthly reports currently show contributors by PR authorship only (merged PRs). This misses valuable community engagement from:\n- Discussion participants (comments, reactions, helpful answers)\n- Issue reporters and triagers\n- Code reviewers\n- Community support providers\n\nWe want a \"Community Engagement\" section alongside the existing contributors section that highlights top community participants based on broader engagement metrics.\n\n## Key Research Questions\n\n1. **What metrics to track?**\n   - Discussion comments/replies\n   - Issue comments (excluding PR comments)\n   - Reactions given/received\n   - Helpful answer marks in discussions\n   - Code review comments\n\n2. **Top 10 or Top 20?**\n   - Depends on activity volume in monitored repos\n   - Need to query live data to determine typical engagement levels\n   - Should avoid showing mostly zeros\n\n3. **New Light subsection?**\n   - Similar to \"🌟 New Contributors\" for first-time PR authors\n   - Could show \"🌟 New Voices\" for first-time discussion/issue participants\n   - Would require historical tracking similar to contributors-history.json\n\n4. **Data sources:**\n   - GitHub Discussions API (projectbluefin/common, ublue-os/bluefin)\n   - GitHub Issues API (all monitored repos)\n   - GitHub Pull Request Review API (all monitored repos)\n\n## Solution\n\n**Phase 1: Research \u0026 Design**\n\n1. Query live GitHub API data for December 2024 and January 2025 (existing report months)\n2. Analyze engagement patterns:\n   - How many unique discussion participants per month?\n   - How many unique issue commenters (non-PR)?\n   - What's the distribution? (Are there 5 active people or 50?)\n3. Determine appropriate threshold:\n   - If 5-15 active: Top 10\n   - If 15-30 active: Top 20\n   - If \u003c5 active: May not be worth separate section\n\n**Phase 2: Implementation**\n\n1. Add GraphQL queries for:\n   - Discussion comments in date range\n   - Issue comments (non-PR) in date range\n   - PR review comments in date range\n2. Build engagement scoring system:\n   - Weight different activity types (discussion reply \u003e reaction)\n   - Filter out bot accounts\n   - Aggregate by author\n3. Add \"Community Engagement\" section to markdown generator:\n   - Top N most engaged community members\n   - Show engagement type breakdown (discussions, issues, reviews)\n   - Optional \"New Voices\" subsection for first-timers\n4. Update historical tracking:\n   - Either extend contributors-history.json to include engagement\n   - Or create separate engagement-history.json\n   - Ensure query-based detection like contributor system\n\n**Phase 3: Validation**\n\n1. Generate test reports with engagement data\n2. Verify bot filtering works correctly\n3. Confirm \"New Voices\" detection is accurate\n4. Check that section adds value (not mostly empty)\n\n## Files Modified\n- scripts/generate-report.mjs\n- scripts/lib/graphql-queries.mjs\n- scripts/lib/markdown-generator.mjs\n- reports/\n\n## Research Starting Points\n- GitHub GraphQL API Explorer: https://docs.github.com/en/graphql/overview/explorer\n- Discussion queries: `repository.discussions` with `comments` connection\n- Issue queries: `repository.issues` with `comments` connection (filter `isPullRequest: false`)\n- Review queries: `repository.pullRequests` with `reviews` connection\n\n## Success Criteria\n- [ ] Live data analysis complete (sample size, distribution)\n- [ ] Top N threshold determined (10 vs 20)\n- [ ] GraphQL queries return engagement metrics\n- [ ] Engagement scoring system designed\n- [ ] Bot filtering verified\n- [ ] Historical tracking approach decided\n- [ ] \"New Voices\" detection implemented (if feasible)\n- [ ] Test reports show valuable engagement data\n\n---\n*Migrated from .planning/todos/pending/2026-01-29-add-community-engagement-section.md (created: 2026-01-29)*","status":"open","priority":2,"issue_type":"feature","owner":"jorge.castro@gmail.com","created_at":"2026-01-31T00:36:49.293306937-05:00","created_by":"Jorge O. Castro","updated_at":"2026-01-31T00:36:49.293306937-05:00","labels":["community","enhancement","reports"]}
 {"id":"bluefin-docs-itu","title":"Add homebrew tap promotion section to monthly reports","description":"## Problem\n\nMonthly reports should include a section showing packages that have been promoted from the experimental-tap to the production-tap during the reporting period. This helps users discover newly production-ready packages.\n\nThe section should:\n- Appear in monthly reports (not in command-line documentation)\n- List packages promoted during the month with descriptions\n- Include a link to http://github.com/ublue-os/homebrew-tap\n- Use specific wording: \"Use `ujust bbrew` to browse and install these packages. Follow [the tap instructions] if you want to do it by hand.\"\n\n## Solution\n\n**Research Promotions Workflow:**\n1. Identify how packages move from experimental-tap to homebrew-tap\n2. Determine what commit messages/patterns indicate a promotion\n3. Example: commit `bd381cf` (Jan 12, 2026) promoted antigravity-linux\n\n**Add Data Fetching to Report Generator:**\n1. Query both experimental-tap and homebrew-tap repositories\n2. Compare commits between taps to detect promotions\n3. Filter commits by date range (report month)\n4. Extract package names and descriptions from formulas/casks\n\n**Add Markdown Generation:**\n1. Create new section in `scripts/lib/markdown-generator.mjs`\n2. Format: \"## Homebrew Tap Promotions\" section\n3. List promoted packages with bullet points\n4. Include package descriptions from formula/cask files\n5. Add footer with usage instructions and tap link\n\n**Integration:**\n1. Wire up in `scripts/generate-report.mjs`\n2. Position section after \"Contributors\" but before footer\n3. Handle case where no promotions occurred (skip section or show \"None this month\")\n\n## Implementation Notes\n\n**Promotion Detection Strategy:**\n\nOption 1: GitHub API commits comparison\n- Fetch commits from both repos in date range\n- Look for new files added to homebrew-tap/Formula or homebrew-tap/Casks\n- Cross-reference with experimental-tap to confirm they existed there first\n\nOption 2: Commit message parsing\n- Look for specific commit patterns like \"feat: promote X to main tap\"\n- Simpler but less reliable if commit messages aren't consistent\n\n**Package Description Extraction:**\n- Parse Ruby formula files to extract `desc` field\n- Example: `desc \"Antigravity application for Linux\"`\n- Cache descriptions to avoid repeated parsing\n\n**Known Promotions (for testing):**\n- antigravity-linux (Jan 12, 2026 - commit bd381cf)\n- goose-linux (frequent updates, check if promotion or just updates)\n- linux-mcp-server (Jan 26, 2026 - commit 90a8c88)\n\n## Files Modified\n- scripts/generate-report.mjs\n- scripts/lib/markdown-generator.mjs\n- reports/\n\n## Success Criteria\n- [ ] Report generator detects promotions from experimental to production tap\n- [ ] Promotions section appears in monthly reports when promotions occurred\n- [ ] Package descriptions accurately extracted from formula files\n- [ ] Section omitted or shows \"None this month\" when no promotions\n- [ ] Usage instructions and tap link included\n- [ ] Test with January 2026 report (known promotions: antigravity, linux-mcp-server)\n\n---\n*Migrated from .planning/todos/pending/2026-01-29-add-homebrew-tap-promotion-section.md (created: 2026-01-29)*","status":"open","priority":2,"issue_type":"feature","owner":"jorge.castro@gmail.com","created_at":"2026-01-31T00:37:06.083488312-05:00","created_by":"Jorge O. Castro","updated_at":"2026-01-31T00:37:06.083488312-05:00","labels":["enhancement","homebrew","reports"]}
-{"id":"bluefin-docs-k89","title":"Upgrade Node.js from 18 to latest LTS version","description":"## Problem\n\nNode.js 18 has reached End of Life (EOL) as of April 2025. The project currently specifies:\n- `package.json` engines: `\"node\": \"\u003e=18.0\"`\n- Monthly reports workflow: `node-version: \"18\"`\n- Other workflows mix Node 20 and \"latest\"\n\nContinuing to use EOL Node versions creates security and compatibility risks:\n- No security patches for vulnerabilities\n- Incompatibility with newer dependencies\n- CI/CD failures as actions drop Node 18 support\n- Package managers may deprecate Node 18 in their own tooling\n\nThe inconsistency across workflows (18 in monthly-reports, 20 in pages/driver-versions, latest in renovate) suggests the upgrade was partially done but not completed.\n\n## Solution\n\n**Recommended:** Upgrade to Node.js 22 LTS (Active LTS as of October 2024, supported until April 2027)\n\n**Upgrade Plan:**\n\n1. **Update Configuration Files:**\n   - `package.json`: Change engines to `\"node\": \"\u003e=22.0\"`\n   - `.github/workflows/monthly-reports.yml`: Change to `node-version: \"22\"`\n   - Standardize all workflows to use Node 22\n\n2. **Test Locally:**\n   - Switch to Node 22: `nvm use 22` or equivalent\n   - Clear node_modules: `rm -rf node_modules package-lock.json`\n   - Reinstall: `npm install --legacy-peer-deps`\n   - Run validation suite:\n     - `npm run typecheck`\n     - `npm run prettier-lint`\n     - `npm run build`\n     - `npm run generate-report -- --month=2026-01`\n   - Test dev server: `npm start`\n\n3. **Verify All Workflows:**\n   - Trigger each workflow manually via GitHub Actions\n   - Verify monthly reports generation still works\n   - Check driver versions update workflow\n   - Validate pages deployment\n\n4. **Update Documentation:**\n   - `AGENTS.md`: Update Node version references (currently mentions 18.x)\n   - `.planning/STATE.md`: Update technical notes section\n   - Update any installation docs\n\n5. **Commit Strategy:**\n   - Single atomic commit with all version bumps\n   - Test in CI before merging\n   - Monitor first production build after merge\n\n**Risk Assessment:**\n- Low risk: Node 22 is LTS and Docusaurus 3.8.1 supports it\n- Potential issues: Dependency peer warnings (already using --legacy-peer-deps)\n- Mitigation: Full test suite before commit\n\n**Alternative:** Node 20 LTS (Maintenance mode, supported until April 2026)\n- Safer short-term option if Node 22 causes issues\n- Would require another upgrade in ~12 months\n\n## Files Modified\n- package.json:9-10\n- .github/workflows/monthly-reports.yml:31\n- .github/workflows/pages.yml\n- .github/workflows/update-driver-versions.yml\n\n## References\n- Node.js release schedule: https://nodejs.org/en/about/previous-releases\n- Docusaurus system requirements: https://docusaurus.io/docs/installation#requirements\n\n---\n*Migrated from .planning/todos/pending/2026-01-28-upgrade-node-18-to-latest-lts.md (created: 2026-01-28)*","status":"open","priority":1,"issue_type":"task","owner":"jorge.castro@gmail.com","created_at":"2026-01-31T00:36:30.816680601-05:00","created_by":"Jorge O. Castro","updated_at":"2026-01-31T00:36:30.816680601-05:00","labels":["dependencies","security","tooling"]}
+{"id":"bluefin-docs-k89","title":"Upgrade Node.js from 18 to latest LTS version","description":"## Problem\n\nNode.js 18 has reached End of Life (EOL) as of April 2025. The project currently specifies:\n- `package.json` engines: `\"node\": \"\u003e=18.0\"`\n- Monthly reports workflow: `node-version: \"18\"`\n- Other workflows mix Node 20 and \"latest\"\n\nContinuing to use EOL Node versions creates security and compatibility risks:\n- No security patches for vulnerabilities\n- Incompatibility with newer dependencies\n- CI/CD failures as actions drop Node 18 support\n- Package managers may deprecate Node 18 in their own tooling\n\nThe inconsistency across workflows (18 in monthly-reports, 20 in pages/driver-versions, latest in renovate) suggests the upgrade was partially done but not completed.\n\n## Solution\n\n**Recommended:** Upgrade to Node.js 22 LTS (Active LTS as of October 2024, supported until April 2027)\n\n**Upgrade Plan:**\n\n1. **Update Configuration Files:**\n   - `package.json`: Change engines to `\"node\": \"\u003e=22.0\"`\n   - `.github/workflows/monthly-reports.yml`: Change to `node-version: \"22\"`\n   - Standardize all workflows to use Node 22\n\n2. **Test Locally:**\n   - Switch to Node 22: `nvm use 22` or equivalent\n   - Clear node_modules: `rm -rf node_modules package-lock.json`\n   - Reinstall: `npm install --legacy-peer-deps`\n   - Run validation suite:\n     - `npm run typecheck`\n     - `npm run prettier-lint`\n     - `npm run build`\n     - `npm run generate-report -- --month=2026-01`\n   - Test dev server: `npm start`\n\n3. **Verify All Workflows:**\n   - Trigger each workflow manually via GitHub Actions\n   - Verify monthly reports generation still works\n   - Check driver versions update workflow\n   - Validate pages deployment\n\n4. **Update Documentation:**\n   - `AGENTS.md`: Update Node version references (currently mentions 18.x)\n   - `.planning/STATE.md`: Update technical notes section\n   - Update any installation docs\n\n5. **Commit Strategy:**\n   - Single atomic commit with all version bumps\n   - Test in CI before merging\n   - Monitor first production build after merge\n\n**Risk Assessment:**\n- Low risk: Node 22 is LTS and Docusaurus 3.8.1 supports it\n- Potential issues: Dependency peer warnings (already using --legacy-peer-deps)\n- Mitigation: Full test suite before commit\n\n**Alternative:** Node 20 LTS (Maintenance mode, supported until April 2026)\n- Safer short-term option if Node 22 causes issues\n- Would require another upgrade in ~12 months\n\n## Files Modified\n- package.json:9-10\n- .github/workflows/monthly-reports.yml:31\n- .github/workflows/pages.yml\n- .github/workflows/update-driver-versions.yml\n\n## References\n- Node.js release schedule: https://nodejs.org/en/about/previous-releases\n- Docusaurus system requirements: https://docusaurus.io/docs/installation#requirements\n\n---\n*Migrated from .planning/todos/pending/2026-01-28-upgrade-node-18-to-latest-lts.md (created: 2026-01-28)*","notes":"PARTIAL COMPLETION FOUND:\n- ✅ All GitHub Actions workflows upgraded to Node 20\n  - pages.yml: node-version: 20\n  - monthly-reports.yml: node-version: \"20\"\n  - update-driver-versions.yml: node-version: \"20\"\n- ❌ package.json engines field still shows: \"node\": \"\u003e=18.0\"\n\nREMAINING WORK:\n- Update package.json engines to require Node 20+\n- Update any documentation mentioning Node 18\n- Test local builds with Node 20\n- Update AGENTS.md if it references Node version","status":"closed","priority":1,"issue_type":"task","owner":"jorge.castro@gmail.com","created_at":"2026-01-31T00:36:30.816680601-05:00","created_by":"Jorge O. Castro","updated_at":"2026-02-01T18:20:47.888066107-05:00","closed_at":"2026-02-01T18:20:47.888066107-05:00","close_reason":"Completed: Updated Node.js requirement to 20+ in package.json, AGENTS.md, README.md, and docs/devcontainers.md. Package-lock.json regenerated. Pull request #613 created for review: https://github.com/projectbluefin/documentation/pull/613","labels":["dependencies","security","tooling"]}
 {"id":"bluefin-docs-lm9","title":"Clean up and archive .planning after migration","description":"After migration is complete:\n- Verify all work items are in beads\n- Archive .planning directory (move to .planning.archived or similar)\n- Update PROJECT-HINTS.md to reference beads instead of .planning\n- Update any documentation that references .planning\n- Commit changes to repository","status":"closed","priority":1,"issue_type":"task","owner":"jorge.castro@gmail.com","created_at":"2026-01-31T00:35:05.429434249-05:00","created_by":"Jorge O. Castro","updated_at":"2026-01-31T00:42:21.163664746-05:00","closed_at":"2026-01-31T00:42:21.163664746-05:00","close_reason":"Migration from .planning to beads complete: created MIGRATION.md documentation, renamed .planning to .planning-archive, and updated AGENTS.md with beads usage guide","dependencies":[{"issue_id":"bluefin-docs-lm9","depends_on_id":"bluefin-docs-9hl","type":"blocks","created_at":"2026-01-31T00:35:05.4306469-05:00","created_by":"Jorge O. Castro"}]}
 {"id":"bluefin-docs-rfy","title":"Test beads setup","description":"Initial test issue to verify beads is working correctly in bluefin-docs repository","status":"closed","priority":2,"issue_type":"task","owner":"jorge.castro@gmail.com","created_at":"2026-01-31T00:32:43.975362391-05:00","created_by":"Jorge O. Castro","updated_at":"2026-01-31T00:33:08.972649459-05:00","closed_at":"2026-01-31T00:33:08.972649459-05:00","close_reason":"Beads setup verified - system working correctly"}
 {"id":"bluefin-docs-sr2","title":"Analyze .planning directory files and content","description":"Once .planning directory is located, read and analyze the markdown files to understand:\n- File naming conventions\n- Content structure (frontmatter, body format)\n- How tasks/issues are represented\n- How dependencies are tracked\n- Status and priority systems\n- Any custom metadata fields","status":"closed","priority":1,"issue_type":"task","owner":"jorge.castro@gmail.com","created_at":"2026-01-31T00:34:56.633580218-05:00","created_by":"Jorge O. Castro","updated_at":"2026-01-31T00:38:03.259678818-05:00","closed_at":"2026-01-31T00:38:03.259678818-05:00","close_reason":"Analysis complete. Todos migrated. No migration script needed - manual migration was appropriate for small number of items.","dependencies":[{"issue_id":"bluefin-docs-sr2","depends_on_id":"bluefin-docs-bdg","type":"blocks","created_at":"2026-01-31T00:34:56.634820589-05:00","created_by":"Jorge O. Castro"}]}

AGENTS.md

@@ -98,6 +98,7 @@ bd dep <issue-id> <depends-on-id>
 ### Labels
 
 Use labels to categorize work:
+
 - `ci-cd`, `validation`, `tooling`, `dependencies`, `security`
 - `reports`, `monthly-reports`, `community-engagement`
 - `documentation`, `automation`, `workflow`
@@ -489,7 +490,7 @@ git push
 
 ## Dependencies
 
-- **Node.js**: Version 18+ required (see package.json engines field)
+- **Node.js**: Version 20+ required (see package.json engines field)
 - **Package Manager**: npm (standard across development and CI/CD)
 - **Docker**: Optional for containerized development
 - **OS**: Works on Linux, macOS, Windows
@@ -1652,6 +1653,7 @@ feat(components)!: redesign ProjectCard with stats API
 7. **Hand off** - Provide context for next session
 
 **CRITICAL RULES:**
+
 - Work is NOT complete until `git push` succeeds
 - NEVER stop before pushing - that leaves work stranded locally
 - NEVER say "ready to push when you are" - YOU must push

README.md

@@ -62,5 +62,5 @@ This is typically caused by peer dependency conflicts during installation. To re
 
 ### Build Requirements
 
-- Node.js 18+ (see `package.json` engines field)
+- Node.js 20+ (see `package.json` engines field)
 - For production builds, the CI uses `bun` but `npm` works for local development

docs/devcontainers.md

@@ -80,7 +80,7 @@ When you add Dev Container configuration, VS Code creates a `.devcontainer` fold
 ```json
 {
   "name": "Node.js",
-  "image": "mcr.microsoft.com/devcontainers/javascript-node:18",
+  "image": "mcr.microsoft.com/devcontainers/javascript-node:20",
   "features": {
     "ghcr.io/devcontainers/features/git:1": {}
   },