feat: Add CI/CD workflows for npm publishing

[pyrotank41]

🚀 Production-Ready Release Automation

New GitHub Actions Workflows

1. npm-publish.yml (Release → npm)

Trigger: When GitHub Release is published
Steps:

• ✅ Run all 237 tests (must pass!)
• ✅ Build TypeScript package
• ✅ Validate version matches release tag
• ✅ Verify build output exists
• ✅ Check if version already published (warning)
• ✅ Publish to npm with provenance
• ✅ Success notification

Safety Features:

• Tests must pass before publish
• Version validation (package.json vs tag)
• Build verification
• npm provenance for security
• Main branch only

2. ci.yml (PR/Push Testing)

Trigger: PRs and pushes to main
Matrix: Node 18 and Node 20
Steps:

• ✅ Install dependencies
• ✅ Run all tests
• ✅ Build package
• ✅ Verify build output
• ✅ Check TypeScript compilation

Ensures code quality before merging!

Documentation

NPM_PUBLISH_SETUP.md

Complete setup guide covering:

• One-time npm token setup
• Simple 3-step release process using npm version
• GitHub CLI and UI workflows
• Pre-release checklist
• Safety features explanation
• Troubleshooting guide
• Version numbering (semver)
• Complete example for v2.0.0 release

CHANGELOG.md

Initial changelog with:

• v2.0.0 release notes (planned for Dec 21, 2025)
• Complete list of breaking changes
• All 3 PRDs documented
• Migration guide reference
• Historical versions (1.0.0 - 1.3.0)

Release Workflow (Recommended)

# 1. Bump version (auto-creates commit + tag)
npm version major -m "chore: release v%s"

# 2. Push to GitHub (including tags)
git push origin main --follow-tags

# 3. Create GitHub Release (triggers workflow)
gh release create v2.0.0 --generate-notes

That's it! GitHub Action handles the rest:

• Tests → Build → Validate → Publish to npm 🚀

Why This Approach?

✅ Industry Standard - Used by Zustand, SWR, React Hook Form, etc. ✅ Simple - 3 commands, fully automated
✅ Safe - Multiple validation steps
✅ Intentional - Manual release creation prevents accidents ✅ Auditable - GitHub Release notes + npm provenance ✅ Flexible - Easy to evolve with future needs

Files Added

• .github/workflows/npm-publish.yml (101 lines)
• .github/workflows/ci.yml (74 lines)
• .github/NPM_PUBLISH_SETUP.md (267 lines)
• CHANGELOG.md (139 lines)

Ready for v2.0.0 release on December 21, 2025! 🎉