From 426d92caba2d2c9e2e29a2c27ceab110869e7f3a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 4 Dec 2025 15:04:32 +0000 Subject: [PATCH 1/5] Initial plan From f8ed69bf322c602838420d7f945cb51771f5f2c5 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 4 Dec 2025 15:08:04 +0000 Subject: [PATCH 2/5] Initial assessment: Review NPM publication readiness Co-authored-by: chrisribe <1999791+chrisribe@users.noreply.github.com> --- package-lock.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/package-lock.json b/package-lock.json index 256ab32..2d6bc81 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "simple-memory-mcp", - "version": "1.0.21", + "version": "1.1.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "simple-memory-mcp", - "version": "1.0.21", + "version": "1.1.1", "license": "MIT", "dependencies": { "@graphql-tools/schema": "^10.0.29", From 76238b0d998b910662db8a1300130bb15c8be952 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 4 Dec 2025 15:13:34 +0000 Subject: [PATCH 3/5] Add NPM publishing documentation and LICENSE file Co-authored-by: chrisribe <1999791+chrisribe@users.noreply.github.com> --- LICENSE | 21 + docs/MAINTENANCE_GUIDE.md | 850 +++++++++++++++++++++++++++++++++++ docs/NPM_PUBLISHING_GUIDE.md | 535 ++++++++++++++++++++++ docs/NPM_QUICK_START.md | 118 +++++ docs/PUBLISHING_CHECKLIST.md | 350 +++++++++++++++ package-lock.json | 209 +++++---- 6 files changed, 2005 insertions(+), 78 deletions(-) create mode 100644 LICENSE create mode 100644 docs/MAINTENANCE_GUIDE.md create mode 100644 docs/NPM_PUBLISHING_GUIDE.md create mode 100644 docs/NPM_QUICK_START.md create mode 100644 docs/PUBLISHING_CHECKLIST.md diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..e677b29 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 chrisribe + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/docs/MAINTENANCE_GUIDE.md b/docs/MAINTENANCE_GUIDE.md new file mode 100644 index 0000000..45551e8 --- /dev/null +++ b/docs/MAINTENANCE_GUIDE.md @@ -0,0 +1,850 @@ +# Package Maintenance Guide + +Complete guide for maintaining `simple-memory-mcp` on NPM over time. + +## ๐Ÿ“‹ Table of Contents + +- [Regular Maintenance Tasks](#regular-maintenance-tasks) +- [Dependency Management](#dependency-management) +- [Version Management](#version-management) +- [Security Maintenance](#security-maintenance) +- [Community Management](#community-management) +- [Performance Monitoring](#performance-monitoring) +- [Things Beginners Often Miss](#things-beginners-often-miss) +- [Long-Term Considerations](#long-term-considerations) + +--- + +## Regular Maintenance Tasks + +### Weekly Tasks (When Active) + +**Monitor Issues & Pull Requests:** +```bash +# Check GitHub notifications +# Respond to issues within 48 hours +# Review pull requests within 1 week +# Label and prioritize appropriately +``` + +**Track Downloads & Usage:** +- Visit: https://npm-stat.com/charts.html?package=simple-memory-mcp +- Monitor trends and spikes +- Investigate sudden drops (could indicate breaking changes) + +**Security Scan:** +```bash +# Check for new vulnerabilities +npm audit + +# If vulnerabilities found, assess and fix +npm audit fix + +# Test after fixes +npm test +``` + +### Monthly Tasks + +**Dependency Updates:** +```bash +# Check for outdated dependencies +npm outdated + +# Update minor/patch versions +npm update + +# Test thoroughly after updates +npm test +npm run test:perf +npm run test:migration + +# Commit if all tests pass +git add package.json package-lock.json +git commit -m "chore: update dependencies" +``` + +**Documentation Review:** +- [ ] Check for broken links in README.md +- [ ] Update screenshots if UI changed +- [ ] Review and update examples if API changed +- [ ] Check if documentation matches current version + +**Performance Check:** +```bash +# Run benchmarks and compare to previous +npm run benchmark + +# Document any significant changes +# Investigate performance regressions +``` + +### Quarterly Tasks + +**Major Dependency Updates:** +```bash +# Review major version updates +npm outdated + +# Update one major dependency at a time +npm install @modelcontextprotocol/sdk@latest + +# Test extensively +npm test +npm run test:perf + +# Check for breaking changes in dependency changelog +# Update code if needed +``` + +**Compatibility Testing:** +- [ ] Test with latest Node.js LTS version +- [ ] Test with latest MCP SDK version +- [ ] Test on different platforms (Windows/Mac/Linux) +- [ ] Test with different MCP clients (VS Code, Claude Desktop) + +**SEO & Discoverability:** +- [ ] Review keywords in package.json +- [ ] Update README for better search ranking +- [ ] Check NPM package page rendering +- [ ] Update badges (build status, version, downloads) + +### Yearly Tasks + +**License & Legal:** +- [ ] Update copyright year in LICENSE (if applicable) +- [ ] Review third-party licenses +- [ ] Check for license compliance + +**Archive & Deprecation:** +- [ ] Decide if package should continue +- [ ] Consider archiving if no longer maintained +- [ ] Deprecate old versions if needed + +--- + +## Dependency Management + +### Philosophy + +**Keep dependencies minimal:** +- Only add dependencies when necessary +- Prefer standard library when possible +- Audit new dependencies before adding + +**Current core dependencies:** +```json +{ + "@modelcontextprotocol/sdk": "MCP protocol implementation", + "better-sqlite3": "SQLite database with performance", + "graphql": "GraphQL query language", + "@graphql-tools/schema": "GraphQL schema building", + "dotenv": "Environment variable management" +} +``` + +### Updating Dependencies + +**Strategy:** +1. Update patch versions freely (1.2.3 โ†’ 1.2.4) +2. Test minor versions carefully (1.2.3 โ†’ 1.3.0) +3. Plan major versions strategically (1.2.3 โ†’ 2.0.0) + +**Process:** +```bash +# 1. Check what's outdated +npm outdated + +# 2. Read changelogs +# Visit each package's GitHub and read CHANGELOG + +# 3. Update incrementally +npm install package-name@latest + +# 4. Test thoroughly +npm test +npm run test:perf + +# 5. Update lockfile +npm install + +# 6. Commit with clear message +git add package.json package-lock.json +git commit -m "chore: update package-name to v2.0.0" +``` + +### Handling Breaking Changes + +**When a dependency introduces breaking changes:** + +1. **Read migration guide** in dependency's changelog +2. **Create a feature branch** for the update +3. **Update code** to work with new version +4. **Update tests** if API changed +5. **Test extensively** on all platforms +6. **Document changes** in your CHANGELOG.md +7. **Consider if it's a breaking change** for your users +8. **Bump version appropriately** (may require major version bump) + +**Example:** +```bash +# Dependency update requires code changes +git checkout -b update-mcp-sdk-v2 + +# Make necessary code changes +# ... + +# Test +npm test + +# Document +echo "- Updated @modelcontextprotocol/sdk to v2.0.0" >> CHANGELOG.md +echo "- BREAKING: Minimum Node.js version now 18+" >> CHANGELOG.md + +# Commit +git add . +git commit -m "feat!: update MCP SDK to v2.0.0" + +# Bump major version (due to breaking change) +npm run version:major + +# Merge and publish +git checkout main +git merge update-mcp-sdk-v2 +npm publish +``` + +### Dependency Security + +**Always check for vulnerabilities:** +```bash +# After any dependency change +npm audit + +# Fix automatically if possible +npm audit fix + +# Manual fix if auto-fix unavailable +npm install vulnerable-package@safe-version +``` + +**Subscribe to security advisories:** +- Enable GitHub Dependabot alerts +- Watch dependency repositories for security issues +- Join security mailing lists for critical dependencies + +--- + +## Version Management + +### Semantic Versioning (SemVer) + +**Format:** MAJOR.MINOR.PATCH (e.g., 1.2.3) + +**When to bump:** +- **PATCH (1.2.3 โ†’ 1.2.4):** Bug fixes, no API changes +- **MINOR (1.2.3 โ†’ 1.3.0):** New features, backward compatible +- **MAJOR (1.2.3 โ†’ 2.0.0):** Breaking changes, API changes + +### Our Versioning Scripts + +```bash +# Automated (our workflow handles this) +# Every commit to main auto-bumps patch version + +# Manual (for releases) +npm run version:patch # Bug fixes +npm run version:minor # New features +npm run version:major # Breaking changes +``` + +### Changelog Maintenance + +**Keep CHANGELOG.md up to date:** + +```markdown +## [Unreleased] + +### Added +- New feature X +- New command Y + +### Changed +- Improved performance of Z + +### Fixed +- Fixed bug in feature A + +## [1.2.0] - 2025-01-15 + +### Added +- Feature that was released +``` + +**When releasing:** +1. Move items from "Unreleased" to new version section +2. Add release date +3. Commit changelog with version bump +4. Create git tag + +### Deprecation Strategy + +**When deprecating features:** + +1. **Announce deprecation** (at least one minor version before removal): + ```typescript + console.warn('DEPRECATED: This feature will be removed in v2.0.0. Use newFeature() instead.'); + ``` + +2. **Document in CHANGELOG:** + ```markdown + ### Deprecated + - `oldFunction()` - Use `newFunction()` instead. Will be removed in v2.0.0. + ``` + +3. **Provide migration path** in documentation + +4. **Remove in next major version** + +**When deprecating entire package:** +```bash +# Mark as deprecated on NPM +npm deprecate simple-memory-mcp "This package is no longer maintained. Use alternative-package instead." + +# Or deprecate specific version range +npm deprecate simple-memory-mcp@"<2.0.0" "Please upgrade to v2.0.0+" +``` + +--- + +## Security Maintenance + +### Regular Security Audits + +**Weekly/Monthly:** +```bash +# Check for vulnerabilities +npm audit + +# Review results +npm audit --json > audit-report.json + +# Fix automatically if safe +npm audit fix + +# For breaking changes, fix manually +npm audit fix --force # โš ๏ธ Be careful, can break things +``` + +### Handling Security Issues + +**If security vulnerability reported:** + +1. **Acknowledge quickly** (within 24 hours) +2. **Assess severity** (use CVSS scores) +3. **Create private fix** (don't announce until fixed) +4. **Test thoroughly** +5. **Publish patch version** +6. **Announce fix** with CVE if applicable +7. **Deprecate vulnerable versions** + +**Template response:** +``` +Thank you for reporting this security issue. + +We take security seriously and will: +1. Investigate the issue immediately +2. Provide a patch within 48-72 hours +3. Notify users via GitHub Security Advisory + +Please do not disclose publicly until we've released a fix. +``` + +### Security Best Practices + +**Never commit secrets:** +```bash +# Use git-secrets or similar tools +# Add pre-commit hooks + +# .gitignore should include: +.env +*.key +*.pem +secrets/ +``` + +**Review pull requests for security:** +- Check for hardcoded credentials +- Look for unsafe dependencies +- Verify input validation +- Check for SQL injection (we use prepared statements โœ“) +- Review file path traversal risks + +**Maintain 2FA on NPM:** +- Keep 2FA enabled on your npm account +- Store backup codes securely +- Use auth-only or auth-and-publish mode + +--- + +## Community Management + +### Responding to Issues + +**Issue triage:** +- Label appropriately: `bug`, `enhancement`, `question`, `good first issue` +- Set priority: `P0` (critical), `P1` (high), `P2` (medium), `P3` (low) +- Assign milestones if applicable +- Close duplicates with link to original + +**Response templates:** + +**Bug report:** +```markdown +Thanks for reporting this issue! + +To help us fix it, please provide: +- [ ] Version of simple-memory-mcp +- [ ] Node.js version +- [ ] Operating system +- [ ] Steps to reproduce +- [ ] Expected vs actual behavior + +We'll investigate and update you soon. +``` + +**Feature request:** +```markdown +Thanks for the suggestion! + +This could be a useful feature. We'll consider it for a future release. + +In the meantime, you might be able to achieve similar results by [workaround]. + +We'll update this issue once we have a decision. +``` + +**Question:** +```markdown +Great question! + +[Answer their question] + +For more information, check out: +- [Link to relevant documentation] +- [Link to similar issue/discussion] + +Does this answer your question? +``` + +### Managing Pull Requests + +**PR review checklist:** +- [ ] Does it solve the stated problem? +- [ ] Are tests included/passing? +- [ ] Is documentation updated? +- [ ] Does it follow code style? +- [ ] Are there breaking changes? +- [ ] Is CHANGELOG.md updated? + +**PR templates:** +```markdown +## Description +[What does this PR do?] + +## Motivation +[Why is this change needed?] + +## Testing +[How was this tested?] + +## Checklist +- [ ] Tests pass +- [ ] Documentation updated +- [ ] CHANGELOG.md updated +- [ ] No breaking changes (or documented if yes) +``` + +### Building Community + +**Encourage contributions:** +- Add CONTRIBUTING.md (optional but helpful) +- Label "good first issue" for beginners +- Thank contributors publicly +- Add contributors to README (optional) + +**Maintain healthy communication:** +- Be respectful and professional +- Respond within reasonable timeframes +- Be open to feedback +- Admit mistakes and learn from them + +--- + +## Performance Monitoring + +### Benchmarking + +**Regular benchmarks:** +```bash +# Run benchmark suite +npm run benchmark + +# Save results for comparison +npm run benchmark > benchmarks/$(date +%Y-%m-%d).txt + +# Compare over time to detect regressions +``` + +**Track key metrics:** +- Store operation time (target: < 0.1ms) +- Search operation time (target: < 0.2ms) +- Memory usage +- Database size growth +- Package size + +### Performance Regressions + +**If performance degrades:** + +1. **Identify the change** that caused it (git bisect) +2. **Profile the code** to find bottleneck +3. **Optimize or revert** +4. **Add performance test** to prevent regression +5. **Document in CHANGELOG** + +**Tools:** +```bash +# Profile Node.js app +node --prof dist/index.js +node --prof-process isolate-*.log + +# Memory profiling +node --inspect dist/index.js +# Use Chrome DevTools + +# Benchmark specific operations +console.time('operation'); +// ... code ... +console.timeEnd('operation'); +``` + +--- + +## Things Beginners Often Miss + +### 1. **Package Size Matters** + +**Don't include unnecessary files:** +```bash +# Check what you're publishing +npm pack --dry-run + +# Common mistakes: +# โŒ Including node_modules (should be in .gitignore) +# โŒ Including test files (large test fixtures) +# โŒ Including source TypeScript (include only dist/) +# โŒ Including .git directory +# โŒ Including database files +``` + +**Our solution:** +```json +{ + "files": [ + "dist/**/*", + "README.md", + "LICENSE" + ] +} +``` + +### 2. **Versioning Discipline** + +**Mistakes beginners make:** +- โŒ Publishing 1.0.0 too early (use 0.x.x for experimental) +- โŒ Breaking changes in patch/minor versions +- โŒ Not following semver consistently +- โŒ Forgetting to bump version before publish +- โŒ Not tagging releases in git + +**Best practice:** +```bash +# Always bump version before publish +npm run version:patch + +# Always create git tag +git tag -a v1.2.3 -m "Release v1.2.3" +git push origin v1.2.3 + +# Never edit published versions (publish new version instead) +``` + +### 3. **Testing Installed Package** + +**Don't just test in development:** +```bash +# Test as if you're a user +npm pack +npm install -g ./simple-memory-mcp-1.1.1.tgz + +# Verify CLI works +simple-memory --version +simple-memory stats + +# Test in a real project +mkdir test-project +cd test-project +npm install -g simple-memory-mcp +# ... test usage ... + +# Clean up +npm uninstall -g simple-memory-mcp +``` + +### 4. **Documentation Drift** + +**Keep docs in sync:** +- โŒ README examples don't work +- โŒ API documentation outdated +- โŒ Screenshots from old version +- โŒ Installation instructions incorrect + +**Solution:** +- Test all README examples +- Update screenshots when UI changes +- Review docs with each release +- Use automated doc generation when possible + +### 5. **Not Reading NPM Output** + +**Pay attention to publish output:** +```bash +npm publish + +# Read warnings: +# โš ๏ธ "package.json: No repository field" +# โš ๏ธ "package.json: No license field" +# โš ๏ธ "This looks like a HUGE package" +``` + +Fix warnings before publishing. + +### 6. **Forgetting Platform Differences** + +**Test on multiple platforms:** +- Line endings (CRLF vs LF) +- Path separators (/ vs \) +- File permissions (chmod +x) +- Case sensitivity +- Native dependencies + +**Our solution:** +```json +{ + "postbuild": "node -e \"if (process.platform !== 'win32') { require('child_process').execSync('chmod +x dist/index.js'); }\"" +} +``` + +### 7. **Not Planning for Scale** + +**What works for 10 users may not work for 10,000:** +- Database migrations (we handle this โœ“) +- Breaking changes (deprecation strategy needed) +- Support load (documentation reduces support burden) +- Download bandwidth (keep package size reasonable) + +### 8. **Ignoring Deprecation Warnings** + +**During development:** +```bash +# You see: +(node:12345) DeprecationWarning: ... + +# Don't ignore! Fix it now while it's easy. +# In 6 months, that deprecated feature might be removed. +``` + +### 9. **Not Having a Rollback Plan** + +**If you publish a broken version:** +```bash +# Option 1: Deprecate bad version +npm deprecate simple-memory-mcp@1.2.0 "This version has critical bugs. Use 1.2.1 instead." + +# Option 2: Unpublish (only within 72 hours) +npm unpublish simple-memory-mcp@1.2.0 + +# Option 3: Publish fix quickly +npm run version:patch +npm publish +``` + +**Prevention:** +- Test thoroughly before publish +- Use `npm publish --dry-run` first +- Have CI/CD run tests before publish + +### 10. **Poor Git Hygiene** + +**Mistakes:** +- โŒ Committing directly to main +- โŒ Not using feature branches +- โŒ No clear commit messages +- โŒ Not using git tags for releases + +**Better approach:** +```bash +# Feature development +git checkout -b feature/new-feature +# ... work ... +git commit -m "feat: add new feature" + +# PR and review +git push origin feature/new-feature +# Create PR on GitHub +# Review and merge + +# Release +git checkout main +git pull +npm run version:minor +git push --follow-tags +npm publish +``` + +--- + +## Long-Term Considerations + +### When to Sunset a Package + +**Signs it might be time to stop:** +- No longer maintained +- Better alternatives exist +- No longer needed (problem solved differently) +- Too much maintenance burden +- Security issues can't be fixed + +**Graceful shutdown process:** + +1. **Announce deprecation:** + ```bash + npm deprecate simple-memory-mcp "This package is no longer maintained. Use [alternative] instead." + ``` + +2. **Update README:** + ```markdown + # โš ๏ธ DEPRECATED + + This package is no longer maintained. + + Please migrate to [alternative-package]. + + ## Migration Guide + [Provide migration instructions] + ``` + +3. **Archive GitHub repository** + - Mark as archived on GitHub + - Disable issues and PRs + - Add prominent notice + +4. **Final security patches only** + - Fix critical security issues + - No new features + +### Transferring Ownership + +**If you want to hand off to someone else:** + +```bash +# NPM ownership +npm owner add new-maintainer simple-memory-mcp +npm owner rm your-username simple-memory-mcp + +# GitHub repository +# Transfer via Settings โ†’ Transfer ownership +``` + +### Keeping Motivation + +**Package maintenance is a marathon, not a sprint:** + +- Set realistic expectations +- It's okay to take breaks +- Ask for help (co-maintainers) +- Celebrate milestones +- Don't feel guilty about saying no to features +- Remember why you created it + +**Automate what you can:** +- Use GitHub Actions for CI/CD +- Automated version bumping (we have this โœ“) +- Automated dependency updates (Dependabot) +- Automated testing +- Automated publishing (optional) + +--- + +## Useful Commands Reference + +```bash +# Version management +npm run version:patch +npm run version:minor +npm run version:major + +# Publishing +npm publish +npm publish --otp=123456 +npm publish --dry-run + +# Package inspection +npm view simple-memory-mcp +npm pack --dry-run +npm outdated + +# Security +npm audit +npm audit fix + +# Testing +npm test +npm run test:perf +npm run test:migration +npm run benchmark + +# Installation testing +npm install -g ./ +npm install -g simple-memory-mcp + +# Deprecation +npm deprecate simple-memory-mcp@1.0.0 "Message" +npm deprecate simple-memory-mcp@"<1.1.0" "Message" + +# Ownership +npm owner ls simple-memory-mcp +npm owner add username simple-memory-mcp +npm owner rm username simple-memory-mcp + +# Stats +npm view simple-memory-mcp versions +npm view simple-memory-mcp time +``` + +--- + +## Resources + +- **NPM Documentation:** https://docs.npmjs.com/ +- **Semantic Versioning:** https://semver.org/ +- **Keep a Changelog:** https://keepachangelog.com/ +- **GitHub Actions:** https://docs.github.com/en/actions +- **Node.js Security:** https://nodejs.org/en/security/ +- **Package Maintenance:** https://github.com/npm/npm/wiki/npm-tricks + +--- + +**Remember:** Good maintenance is about consistency, not perfection. Do what you can, automate what makes sense, and ask for help when needed. ๐Ÿš€ diff --git a/docs/NPM_PUBLISHING_GUIDE.md b/docs/NPM_PUBLISHING_GUIDE.md new file mode 100644 index 0000000..368fa0b --- /dev/null +++ b/docs/NPM_PUBLISHING_GUIDE.md @@ -0,0 +1,535 @@ +# NPM Publishing Guide for Simple Memory MCP + +Complete step-by-step guide to publish `simple-memory-mcp` to NPM. + +## ๐Ÿ“‹ Table of Contents + +- [Prerequisites](#prerequisites) +- [Pre-Publication Checklist](#pre-publication-checklist) +- [Publishing Steps](#publishing-steps) +- [Post-Publication Tasks](#post-publication-tasks) +- [Updating Published Package](#updating-published-package) +- [Troubleshooting](#troubleshooting) + +--- + +## Prerequisites + +### 1. NPM Account Setup + +**First-time publishers:** +```bash +# Create account at https://www.npmjs.com/signup +# Or via CLI: +npm adduser +``` + +**Existing account:** +```bash +# Login to npm +npm login + +# Verify you're logged in +npm whoami +``` + +### 2. Two-Factor Authentication (2FA) + +**Highly recommended for package security:** + +1. Go to https://www.npmjs.com/settings/[your-username]/tfa +2. Enable 2FA (choose "Authorization and Publishing" for maximum security) +3. Save backup codes in a secure location + +**Note:** With 2FA enabled, you'll need to append a one-time password when publishing: +```bash +npm publish --otp=123456 +``` + +### 3. Package Name Verification + +```bash +# Check if name is available +npm view simple-memory-mcp + +# If you see "404 Not Found" or "Unpublished", the name is available +# If you see package details, the name is taken (unlikely for this package) +``` + +**Our status:** `simple-memory-mcp` was previously published but unpublished on 2025-06-21. The name is now available for re-publishing. + +--- + +## Pre-Publication Checklist + +Use the [PUBLISHING_CHECKLIST.md](./PUBLISHING_CHECKLIST.md) for a detailed verification list. Key items: + +### Critical Checks + +- [ ] **All tests pass:** `npm test` +- [ ] **Build succeeds:** `npm run build` +- [ ] **No security vulnerabilities:** `npm audit` (should show 0 vulnerabilities) +- [ ] **LICENSE file exists** (MIT license) +- [ ] **README.md is complete** with installation instructions +- [ ] **package.json metadata is correct:** + - [ ] Name: `simple-memory-mcp` + - [ ] Version follows semver (e.g., `1.1.1`) + - [ ] Description is clear and concise + - [ ] Keywords are relevant for discoverability + - [ ] Repository URL is correct + - [ ] License is "MIT" + - [ ] Author is set + - [ ] Main entry point: `dist/index.js` + - [ ] Binary command: `simple-memory` + +### Files Configuration + +Verify what will be published: +```bash +# Dry run to see included files +npm pack --dry-run + +# Should include only: +# - dist/** (compiled JavaScript) +# - README.md +# - LICENSE +# - package.json +``` + +**What NOT to publish:** +- Source TypeScript files (src/) +- Test files +- Development configuration files +- node_modules/ +- Database files (*.db*) +- Environment files (.env) + +Our configuration uses the `"files"` array in package.json to control this. + +### Version Check + +```bash +# Current version +npm version + +# Ensure version follows semantic versioning: +# MAJOR.MINOR.PATCH (e.g., 1.1.1) +``` + +**Version number guidelines:** +- **MAJOR:** Breaking changes (e.g., 1.x.x โ†’ 2.0.0) +- **MINOR:** New features, backward compatible (e.g., 1.1.x โ†’ 1.2.0) +- **PATCH:** Bug fixes, backward compatible (e.g., 1.1.1 โ†’ 1.1.2) + +--- + +## Publishing Steps + +### Step 1: Final Preparation + +```bash +# 1. Ensure you're on the main branch and it's up to date +git checkout main +git pull origin main + +# 2. Clean install dependencies +rm -rf node_modules package-lock.json +npm install + +# 3. Run full test suite +npm test +npm run test:perf +npm run test:migration + +# 4. Clean build +rm -rf dist +npm run build + +# 5. Verify package contents +npm pack --dry-run +``` + +### Step 2: Version Bump (if needed) + +If you need to bump the version before publishing: + +```bash +# For patch release (bug fixes): 1.1.1 โ†’ 1.1.2 +npm run version:patch + +# For minor release (new features): 1.1.1 โ†’ 1.2.0 +npm run version:minor + +# For major release (breaking changes): 1.1.1 โ†’ 2.0.0 +npm run version:major + +# This automatically updates: +# - package.json version +# - Creates git tag +# - Updates CHANGELOG.md (if applicable) +``` + +**Note:** Our automated version bump workflow handles this on commits to main, so manual version bumps are typically only needed for manual releases. + +### Step 3: Publish to NPM + +```bash +# Standard publish (public package) +npm publish + +# With 2FA (append one-time password) +npm publish --otp=123456 + +# First-time publish should succeed if name is available +``` + +**Expected output:** +``` ++ simple-memory-mcp@1.1.1 +``` + +### Step 4: Verify Publication + +```bash +# Check package page +npm view simple-memory-mcp + +# Should show: +# - Version number +# - Description +# - Dependencies +# - Dist-tags +# - etc. + +# Visit package page +# https://www.npmjs.com/package/simple-memory-mcp +``` + +### Step 5: Test Installation + +**Test in a fresh environment:** + +```bash +# Create test directory +mkdir /tmp/test-npm-install +cd /tmp/test-npm-install + +# Global installation test +npm install -g simple-memory-mcp + +# Verify command is available +simple-memory --version +simple-memory stats + +# Test basic functionality +simple-memory store --content "Test memory" --tags "test" +simple-memory search --query "Test" + +# Cleanup +npm uninstall -g simple-memory-mcp +cd - +rm -rf /tmp/test-npm-install +``` + +--- + +## Post-Publication Tasks + +### 1. Create Git Tag and Release + +```bash +# Tag the release (if not already done by version bump) +git tag -a v1.1.1 -m "Release version 1.1.1" +git push origin v1.1.1 + +# Create GitHub Release +# Go to: https://github.com/chrisribe/simple-memory-mcp/releases/new +# - Select tag: v1.1.1 +# - Title: "v1.1.1 - [Brief description]" +# - Description: Copy from CHANGELOG.md +# - Attach binaries if applicable +# - Click "Publish release" +``` + +### 2. Update Documentation + +- [ ] Update README.md installation instructions (if changed) +- [ ] Add release notes to CHANGELOG.md +- [ ] Update any version references in documentation +- [ ] Verify npm badges show correct version + +### 3. Announce the Release + +Consider announcing on: +- [ ] GitHub Discussions +- [ ] Project Discord/Slack (if applicable) +- [ ] Twitter/Social media +- [ ] Dev.to or Medium (if you blog) + +**Sample announcement:** +``` +๐ŸŽ‰ simple-memory-mcp v1.1.1 is now available on NPM! + +A blazingly fast MCP server for persistent memory storage with intelligent +tagging and full-text search. + +Install: npm install -g simple-memory-mcp + +Features: +- Sub-millisecond performance +- Full-text search with SQLite FTS5 +- Smart tagging and auto-relationships +- Zero-config setup + +https://www.npmjs.com/package/simple-memory-mcp +https://github.com/chrisribe/simple-memory-mcp +``` + +### 4. Monitor Initial Usage + +**First 24-48 hours:** +- [ ] Check npm download stats: https://npm-stat.com/charts.html?package=simple-memory-mcp +- [ ] Monitor GitHub issues for installation problems +- [ ] Watch for community feedback + +--- + +## Updating Published Package + +### For Patch/Minor Updates + +```bash +# 1. Make your changes +# 2. Test thoroughly +npm test + +# 3. Build +npm run build + +# 4. Bump version +npm run version:patch # or version:minor + +# 5. Publish +npm publish --otp=123456 # if using 2FA +``` + +### For Major Updates (Breaking Changes) + +**Extra care required:** + +1. **Update CHANGELOG.md** with clear migration guide +2. **Document breaking changes** in README.md +3. **Consider deprecation warnings** before removing features +4. **Test extensively** with real-world use cases +5. **Bump to next major version:** `npm run version:major` +6. **Publish with release notes** + +### Deprecating Old Versions + +If you need to deprecate an old version: + +```bash +# Deprecate a specific version +npm deprecate simple-memory-mcp@1.0.0 "Please upgrade to v1.1.0 or higher" + +# Deprecate all versions below a certain version +npm deprecate simple-memory-mcp@"<1.1.0" "Version 1.1.0+ required for security fixes" +``` + +--- + +## Troubleshooting + +### Common Issues + +#### 1. "You do not have permission to publish" + +**Solution:** +```bash +# Verify you're logged in +npm whoami + +# If not logged in: +npm login + +# Check package.json name doesn't conflict +npm view simple-memory-mcp +``` + +#### 2. "Package name too similar to existing package" + +**Solution:** +- If legitimate conflict, consider scoped package: `@chrisribe/simple-memory-mcp` +- Update package.json: `"name": "@chrisribe/simple-memory-mcp"` +- Publish scoped package: `npm publish --access=public` + +#### 3. "Version already exists" + +**Solution:** +```bash +# Check current published version +npm view simple-memory-mcp version + +# Bump to next version +npm run version:patch +npm publish +``` + +#### 4. "npm ERR! 403 Forbidden" + +**Possible causes:** +- 2FA required but not provided: Use `--otp=123456` +- Not logged in: Run `npm login` +- No permission for scoped package: Use `--access=public` +- Package name taken: Change package name + +#### 5. "prepublishOnly script failed" + +**Solution:** +```bash +# Our prepublishOnly runs build +# If it fails, check build errors: +npm run build + +# Fix TypeScript errors, then retry +npm publish +``` + +### Testing Package Locally Before Publishing + +**Use `npm link` for local testing:** + +```bash +# In package directory +npm link + +# In another project +npm link simple-memory-mcp + +# Test functionality +# ... + +# Unlink when done +npm unlink simple-memory-mcp # in test project +npm unlink -g # in package directory +``` + +**Or use tarball:** + +```bash +# Create tarball +npm pack + +# Install in test project +cd /path/to/test/project +npm install /path/to/simple-memory-mcp-1.1.1.tgz + +# Test, then cleanup +npm uninstall simple-memory-mcp +``` + +--- + +## Security Best Practices + +### 1. Enable 2FA + +**Mandatory for popular packages:** +- Go to npm settings +- Enable 2FA for "Authorization and Publishing" +- Keep backup codes safe + +### 2. Audit Dependencies Regularly + +```bash +# Check for vulnerabilities +npm audit + +# Fix automatically +npm audit fix + +# Check before every publish +``` + +### 3. Review Package Contents + +**Before publishing, always check:** +```bash +npm pack --dry-run + +# Ensure no sensitive data: +# - No .env files +# - No private keys +# - No database files +# - No credentials +``` + +### 4. Use .npmignore or "files" in package.json + +We use the `"files"` array in package.json for explicit control: +```json +{ + "files": [ + "dist/**/*", + "README.md", + "LICENSE" + ] +} +``` + +This is safer than `.npmignore` (whitelist vs blacklist). + +### 5. Avoid Typosquatting + +- Use exact package name in documentation +- Monitor for similar package names +- Report suspicious packages to npm + +--- + +## Additional Resources + +- **NPM Documentation:** https://docs.npmjs.com/ +- **Semantic Versioning:** https://semver.org/ +- **Package.json Guide:** https://docs.npmjs.com/cli/v10/configuring-npm/package-json +- **Publishing Packages:** https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry +- **Package Security:** https://docs.npmjs.com/packages-and-modules/securing-your-code + +--- + +## Quick Reference + +```bash +# Login +npm login + +# Verify login +npm whoami + +# Check package availability +npm view simple-memory-mcp + +# Dry run package contents +npm pack --dry-run + +# Bump version +npm run version:patch + +# Publish +npm publish + +# Publish with 2FA +npm publish --otp=123456 + +# Check published package +npm view simple-memory-mcp + +# Test install +npm install -g simple-memory-mcp +``` + +--- + +**Ready to publish? ๐Ÿš€** + +Follow the [PUBLISHING_CHECKLIST.md](./PUBLISHING_CHECKLIST.md) to ensure you haven't missed anything! diff --git a/docs/NPM_QUICK_START.md b/docs/NPM_QUICK_START.md new file mode 100644 index 0000000..118658a --- /dev/null +++ b/docs/NPM_QUICK_START.md @@ -0,0 +1,118 @@ +# NPM Publishing Quick Start + +**TL;DR version of the publishing guide for experienced developers.** + +## Prerequisites โœ“ + +```bash +npm login +npm whoami # Verify +``` + +## Pre-Publish Checklist โœ“ + +```bash +# 1. Clean & Install +rm -rf node_modules package-lock.json && npm install + +# 2. Security +npm audit # Must show 0 vulnerabilities + +# 3. Build +rm -rf dist && npm run build + +# 4. Test +npm test && npm run test:perf && npm run test:migration + +# 5. Verify package +npm pack --dry-run + +# 6. Version check +cat package.json | grep version +``` + +## Publish ๐Ÿš€ + +```bash +# Standard +npm publish + +# With 2FA +npm publish --otp=123456 +``` + +## Post-Publish โœ“ + +```bash +# 1. Git tag +git tag -a v1.1.1 -m "Release v1.1.1" +git push origin v1.1.1 + +# 2. Verify +npm view simple-memory-mcp +npm install -g simple-memory-mcp +simple-memory --version + +# 3. GitHub Release +# https://github.com/chrisribe/simple-memory-mcp/releases/new +``` + +## Update Package ๐Ÿ”„ + +```bash +# 1. Make changes & test +npm test + +# 2. Bump version +npm run version:patch # or minor, major + +# 3. Publish +npm publish --otp=123456 + +# 4. Tag & push +git push --follow-tags +``` + +--- + +## Common Issues ๐Ÿ”ง + +**"Permission denied"** +```bash +npm login +``` + +**"Version already exists"** +```bash +npm run version:patch +``` + +**"Vulnerabilities found"** +```bash +npm audit fix +npm test # Verify still works +``` + +**"Package too large"** +```bash +npm pack --dry-run # Check what's included +# Verify "files" array in package.json +``` + +--- + +## Full Documentation + +- ๐Ÿ“˜ [Complete Publishing Guide](./NPM_PUBLISHING_GUIDE.md) +- โœ… [Detailed Checklist](./PUBLISHING_CHECKLIST.md) +- ๐Ÿ› ๏ธ [Maintenance Guide](./MAINTENANCE_GUIDE.md) + +--- + +## One-Liner Publish (For Advanced Users) + +```bash +git status && npm audit && npm run build && npm test && npm pack --dry-run && npm publish --otp=$(read -p "OTP: " otp && echo $otp) && git push --follow-tags +``` + +**Use with caution!** This skips verification steps. diff --git a/docs/PUBLISHING_CHECKLIST.md b/docs/PUBLISHING_CHECKLIST.md new file mode 100644 index 0000000..0abbc28 --- /dev/null +++ b/docs/PUBLISHING_CHECKLIST.md @@ -0,0 +1,350 @@ +# NPM Publishing Checklist + +Use this checklist before publishing to NPM to ensure quality and avoid common mistakes. + +## ๐ŸŽฏ Pre-Flight Checks (Critical) + +### Package Identity +- [ ] Package name is correct and available: `simple-memory-mcp` +- [ ] Version follows semver (MAJOR.MINOR.PATCH format) +- [ ] Version is higher than the last published version +- [ ] Description is clear, concise, and accurate (< 150 chars ideal) + +### Legal & Licensing +- [ ] LICENSE file exists and is correct (MIT) +- [ ] LICENSE is referenced in package.json +- [ ] No copyright violations in code or documentation +- [ ] Third-party licenses are properly attributed (if applicable) + +### Code Quality +- [ ] All TypeScript compiles without errors: `npm run build` +- [ ] All tests pass: `npm test` +- [ ] Performance tests pass: `npm run test:perf` +- [ ] Migration tests pass: `npm run test:migration` +- [ ] No ESLint/TSLint errors (if applicable) +- [ ] Code is properly formatted + +### Security +- [ ] No security vulnerabilities: `npm audit` shows 0 vulnerabilities +- [ ] Dependencies are up to date +- [ ] No secrets/credentials in code or config files +- [ ] No .env files included in package +- [ ] Sensitive data properly excluded via "files" array + +### Package Contents +- [ ] Verified package contents: `npm pack --dry-run` +- [ ] Only necessary files included (dist/, README.md, LICENSE) +- [ ] Source files (src/) excluded +- [ ] Test files excluded +- [ ] Database files (*.db*) excluded +- [ ] node_modules excluded +- [ ] Development config files excluded +- [ ] Total package size is reasonable (< 5MB unpacked ideal) + +### Documentation +- [ ] README.md is comprehensive and up to date +- [ ] Installation instructions are clear +- [ ] Usage examples work as documented +- [ ] API documentation is accurate +- [ ] CHANGELOG.md updated with latest changes +- [ ] All code examples have been tested +- [ ] Links in README work (no 404s) + +### package.json Metadata +- [ ] `"name"` is correct +- [ ] `"version"` is correct +- [ ] `"description"` is accurate and helpful +- [ ] `"keywords"` are relevant for discoverability (check we have: mcp, model-context-protocol, memory, storage, sqlite, tags, ai, llm) +- [ ] `"author"` is set correctly +- [ ] `"license"` is "MIT" +- [ ] `"main"` points to `dist/index.js` +- [ ] `"type": "module"` is set (for ES modules) +- [ ] `"bin"` is configured for CLI: `simple-memory` +- [ ] `"files"` array correctly lists what to include +- [ ] `"repository"` URL is correct +- [ ] `"bugs"` URL is correct +- [ ] `"homepage"` URL is correct + +### Scripts +- [ ] `"prepublishOnly"` runs build: `npm run build` +- [ ] `"postbuild"` makes CLI executable (Unix) +- [ ] All npm scripts work as expected +- [ ] No broken script references + +### Dependencies +- [ ] All dependencies are necessary (no unused packages) +- [ ] Versions are pinned or use reasonable ranges +- [ ] Dev dependencies are in `devDependencies`, not `dependencies` +- [ ] Peer dependencies documented (if applicable) +- [ ] Native dependencies work on target platforms + +--- + +## ๐Ÿš€ Functional Testing + +### Installation Tests +- [ ] Global install works: `npm install -g ./` (from package directory) +- [ ] CLI command available: `simple-memory --version` +- [ ] CLI command works: `simple-memory stats` +- [ ] Uninstall works: `npm uninstall -g simple-memory-mcp` + +### Feature Tests +- [ ] MCP server starts without errors +- [ ] Store memory works: `simple-memory store --content "test"` +- [ ] Search works: `simple-memory search --query "test"` +- [ ] GraphQL queries work: `simple-memory graphql --query "{ stats { totalMemories } }"` +- [ ] Export/import works +- [ ] All shortcut commands work +- [ ] Help displays correctly: `simple-memory --help` +- [ ] Version displays correctly: `simple-memory --version` + +### Cross-Platform Tests +- [ ] Tested on Linux (if applicable) +- [ ] Tested on macOS (if applicable) +- [ ] Tested on Windows (if applicable) +- [ ] Shebang in dist/index.js is correct: `#!/usr/bin/env node` +- [ ] File permissions are correct (executable flag on Unix) + +### Integration Tests +- [ ] Works with VS Code MCP client +- [ ] Works with Claude Desktop (if applicable) +- [ ] Works as MCP server (stdio transport) +- [ ] Works as HTTP server (if applicable) +- [ ] Database migrations work correctly + +--- + +## ๐Ÿ“Š Publishing Environment + +### NPM Account +- [ ] Logged in to NPM: `npm whoami` +- [ ] Account has publish permissions +- [ ] 2FA is enabled on NPM account (recommended) +- [ ] Have access to 2FA codes/app if required + +### Git Repository +- [ ] All changes committed +- [ ] Working directory is clean: `git status` +- [ ] On correct branch (main) +- [ ] Branch is up to date: `git pull origin main` +- [ ] No merge conflicts + +### Version Control +- [ ] Git tag will be created for this version +- [ ] GitHub release notes prepared +- [ ] CHANGELOG.md reflects this version + +--- + +## ๐ŸŽจ Optional Quality Checks + +### Documentation Polish +- [ ] Badges in README are up to date +- [ ] Screenshots/GIFs are current (if applicable) +- [ ] Contributing guidelines exist (optional) +- [ ] Code of conduct exists (optional for larger projects) +- [ ] Acknowledgments/credits are complete + +### SEO & Discoverability +- [ ] Package name is searchable and memorable +- [ ] Keywords cover main use cases +- [ ] Description contains main keywords +- [ ] README has clear value proposition in first paragraph +- [ ] Examples are practical and relatable + +### Community +- [ ] GitHub issues template (optional) +- [ ] Pull request template (optional) +- [ ] Discussion board enabled (optional) + +--- + +## โšก Pre-Publish Commands + +Run these in sequence before `npm publish`: + +```bash +# 1. Clean state +git status # Should be clean +npm whoami # Should show your username + +# 2. Clean install +rm -rf node_modules package-lock.json +npm install + +# 3. Security check +npm audit # Should show 0 vulnerabilities + +# 4. Build +rm -rf dist +npm run build # Should succeed + +# 5. Test everything +npm test # All tests pass +npm run test:perf # Performance tests pass +npm run test:migration # Migration tests pass + +# 6. Verify package contents +npm pack --dry-run # Review file list + +# 7. Version check +npm version # Verify version number + +# 8. Test install locally +npm install -g ./ +simple-memory --version +simple-memory stats +npm uninstall -g simple-memory-mcp +``` + +--- + +## ๐Ÿ“ฆ Publishing Commands + +```bash +# Standard publish +npm publish + +# With 2FA +npm publish --otp=123456 + +# First-time publish of scoped package +npm publish --access=public + +# Dry run (test without publishing) +npm publish --dry-run +``` + +--- + +## โœ… Post-Publish Verification + +### Immediate Checks +- [ ] Package appears on NPM: https://www.npmjs.com/package/simple-memory-mcp +- [ ] Correct version is shown +- [ ] README renders correctly on NPM +- [ ] Install works: `npm install -g simple-memory-mcp` +- [ ] Downloaded package works as expected + +### Git Tasks +- [ ] Create and push git tag: `git tag -a v1.1.1 -m "Release v1.1.1"` +- [ ] Push tag: `git push origin v1.1.1` +- [ ] Create GitHub Release with changelog + +### Monitoring +- [ ] Watch for issues in first 24 hours +- [ ] Monitor download stats +- [ ] Check for community feedback + +--- + +## ๐Ÿšจ Red Flags - Stop Publishing If: + +- โŒ Any tests fail +- โŒ npm audit shows vulnerabilities +- โŒ Build fails or has errors +- โŒ Package size > 10MB (investigate why) +- โŒ Wrong version number +- โŒ Missing LICENSE file +- โŒ Secrets/credentials in code +- โŒ Not logged in to npm +- โŒ Git working directory is dirty +- โŒ README has broken links or examples +- โŒ CLI doesn't work when installed globally + +--- + +## ๐Ÿ“ Checklist Summary + +**Before you run `npm publish`, you should have checked off:** + +**Critical (Must Have):** +- All code quality checks pass โœ“ +- All security checks pass โœ“ +- Package contents verified โœ“ +- Documentation complete โœ“ +- Functional tests pass โœ“ + +**Recommended (Should Have):** +- Cross-platform testing โœ“ +- Git repository clean โœ“ +- Version control ready โœ“ + +**Optional (Nice to Have):** +- Community documentation โœ“ +- SEO optimization โœ“ + +--- + +## ๐ŸŽฏ Quick Pre-Publish Script + +Save this as a script to run before publishing: + +```bash +#!/bin/bash +# pre-publish-check.sh + +echo "๐Ÿ” Running pre-publish checks..." + +# Clean state +if [[ -n $(git status -s) ]]; then + echo "โŒ Git working directory is not clean" + exit 1 +fi + +# Dependencies +echo "๐Ÿ“ฆ Installing dependencies..." +rm -rf node_modules package-lock.json +npm install + +# Security +echo "๐Ÿ”’ Checking security..." +if npm audit | grep -q "vulnerabilities"; then + echo "โŒ Security vulnerabilities found" + npm audit + exit 1 +fi + +# Build +echo "๐Ÿ”จ Building..." +rm -rf dist +npm run build || exit 1 + +# Tests +echo "๐Ÿงช Running tests..." +npm test || exit 1 +npm run test:perf || exit 1 +npm run test:migration || exit 1 + +# Package contents +echo "๐Ÿ“‹ Checking package contents..." +npm pack --dry-run + +echo "" +echo "โœ… All pre-publish checks passed!" +echo "๐Ÿ“ฆ Ready to publish with: npm publish" +echo "" +echo "Version: $(node -p "require('./package.json').version")" +echo "Files: $(npm pack --dry-run 2>&1 | grep 'total files' | awk '{print $3}')" +``` + +Make it executable: +```bash +chmod +x pre-publish-check.sh +``` + +Run before publishing: +```bash +./pre-publish-check.sh && npm publish +``` + +--- + +**๐ŸŽ‰ Ready to Publish?** + +If all checks pass, proceed with confidence: +```bash +npm publish --otp=123456 # if using 2FA +``` + +Good luck! ๐Ÿš€ diff --git a/package-lock.json b/package-lock.json index 2d6bc81..3a17a08 100644 --- a/package-lock.json +++ b/package-lock.json @@ -507,12 +507,13 @@ } }, "node_modules/@modelcontextprotocol/sdk": { - "version": "1.17.3", - "resolved": "https://registry.npmjs.org/@modelcontextprotocol/sdk/-/sdk-1.17.3.tgz", - "integrity": "sha512-JPwUKWSsbzx+DLFznf/QZ32Qa+ptfbUlHhRLrBQBAFu9iI1iYvizM4p+zhhRDceSsPutXp4z+R/HPVphlIiclg==", + "version": "1.24.3", + "resolved": "https://registry.npmjs.org/@modelcontextprotocol/sdk/-/sdk-1.24.3.tgz", + "integrity": "sha512-YgSHW29fuzKKAHTGe9zjNoo+yF8KaQPzDC2W9Pv41E7/57IfY+AMGJ/aDFlgTLcVVELoggKE4syABCE75u3NCw==", "license": "MIT", "dependencies": { - "ajv": "^6.12.6", + "ajv": "^8.17.1", + "ajv-formats": "^3.0.1", "content-type": "^1.0.5", "cors": "^2.8.5", "cross-spawn": "^7.0.5", @@ -520,13 +521,26 @@ "eventsource-parser": "^3.0.0", "express": "^5.0.1", "express-rate-limit": "^7.5.0", + "jose": "^6.1.1", "pkce-challenge": "^5.0.0", "raw-body": "^3.0.0", - "zod": "^3.23.8", - "zod-to-json-schema": "^3.24.1" + "zod": "^3.25 || ^4.0", + "zod-to-json-schema": "^3.25.0" }, "engines": { "node": ">=18" + }, + "peerDependencies": { + "@cfworker/json-schema": "^4.1.1", + "zod": "^3.25 || ^4.0" + }, + "peerDependenciesMeta": { + "@cfworker/json-schema": { + "optional": true + }, + "zod": { + "optional": false + } } }, "node_modules/@types/better-sqlite3": { @@ -574,21 +588,38 @@ } }, "node_modules/ajv": { - "version": "6.12.6", - "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.12.6.tgz", - "integrity": "sha512-j3fVLgvTo527anyYyJOGTYJbG+vnnQYvE0m5mmkc1TK+nxAppkCLMIL0aZ4dblVCNoGShhm+kzE4ZUykBoMg4g==", + "version": "8.17.1", + "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.17.1.tgz", + "integrity": "sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g==", "license": "MIT", "dependencies": { - "fast-deep-equal": "^3.1.1", - "fast-json-stable-stringify": "^2.0.0", - "json-schema-traverse": "^0.4.1", - "uri-js": "^4.2.2" + "fast-deep-equal": "^3.1.3", + "fast-uri": "^3.0.1", + "json-schema-traverse": "^1.0.0", + "require-from-string": "^2.0.2" }, "funding": { "type": "github", "url": "https://github.com/sponsors/epoberezkin" } }, + "node_modules/ajv-formats": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/ajv-formats/-/ajv-formats-3.0.1.tgz", + "integrity": "sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ==", + "license": "MIT", + "dependencies": { + "ajv": "^8.0.0" + }, + "peerDependencies": { + "ajv": "^8.0.0" + }, + "peerDependenciesMeta": { + "ajv": { + "optional": true + } + } + }, "node_modules/base64-js": { "version": "1.5.1", "resolved": "https://registry.npmjs.org/base64-js/-/base64-js-1.5.1.tgz", @@ -644,23 +675,27 @@ } }, "node_modules/body-parser": { - "version": "2.2.0", - "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.2.0.tgz", - "integrity": "sha512-02qvAaxv8tp7fBa/mw1ga98OGm+eCbqzJOKoRt70sLmfEEi+jyBYVTDGfCL/k06/4EMk/z01gCe7HoCH/f2LTg==", + "version": "2.2.1", + "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.2.1.tgz", + "integrity": "sha512-nfDwkulwiZYQIGwxdy0RUmowMhKcFVcYXUU7m4QlKYim1rUtg83xm2yjZ40QjDuc291AJjjeSc9b++AWHSgSHw==", "license": "MIT", "dependencies": { "bytes": "^3.1.2", "content-type": "^1.0.5", - "debug": "^4.4.0", + "debug": "^4.4.3", "http-errors": "^2.0.0", - "iconv-lite": "^0.6.3", + "iconv-lite": "^0.7.0", "on-finished": "^2.4.1", "qs": "^6.14.0", - "raw-body": "^3.0.0", - "type-is": "^2.0.0" + "raw-body": "^3.0.1", + "type-is": "^2.0.1" }, "engines": { "node": ">=18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" } }, "node_modules/buffer": { @@ -809,9 +844,9 @@ } }, "node_modules/debug": { - "version": "4.4.1", - "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.1.tgz", - "integrity": "sha512-KcKCqiftBJcZr++7ykoDIEwSa3XWowTfNPo92BYxjXiyYEVrUQh2aLyhxBCwww+heortUFxEJYcRzosstTEBYQ==", + "version": "4.4.3", + "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz", + "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==", "license": "MIT", "dependencies": { "ms": "^2.1.3" @@ -1096,11 +1131,21 @@ "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==", "license": "MIT" }, - "node_modules/fast-json-stable-stringify": { - "version": "2.1.0", - "resolved": "https://registry.npmjs.org/fast-json-stable-stringify/-/fast-json-stable-stringify-2.1.0.tgz", - "integrity": "sha512-lhd/wF+Lk98HZoTCtlVraHtfh5XYijIjalXck7saUtuanSDyLMxnHhSXEDJqHxD7msR8D0uCmqlkwjCV8xvwHw==", - "license": "MIT" + "node_modules/fast-uri": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.0.tgz", + "integrity": "sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/fastify" + }, + { + "type": "opencollective", + "url": "https://opencollective.com/fastify" + } + ], + "license": "BSD-3-Clause" }, "node_modules/file-uri-to-path": { "version": "1.0.0", @@ -1274,31 +1319,39 @@ } }, "node_modules/http-errors": { - "version": "2.0.0", - "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.0.tgz", - "integrity": "sha512-FtwrG/euBzaEjYeRqOgly7G0qviiXoJWnvEH2Z1plBdXgbyjv34pHTSb9zoeHMyDy33+DWy5Wt9Wo+TURtOYSQ==", + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.1.tgz", + "integrity": "sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==", "license": "MIT", "dependencies": { - "depd": "2.0.0", - "inherits": "2.0.4", - "setprototypeof": "1.2.0", - "statuses": "2.0.1", - "toidentifier": "1.0.1" + "depd": "~2.0.0", + "inherits": "~2.0.4", + "setprototypeof": "~1.2.0", + "statuses": "~2.0.2", + "toidentifier": "~1.0.1" }, "engines": { "node": ">= 0.8" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" } }, "node_modules/iconv-lite": { - "version": "0.6.3", - "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz", - "integrity": "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==", + "version": "0.7.0", + "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.7.0.tgz", + "integrity": "sha512-cf6L2Ds3h57VVmkZe+Pn+5APsT7FpqJtEhhieDCvrE2MK5Qk9MyffgQyuxQTm6BChfeZNtcOLHp9IcWRVcIcBQ==", "license": "MIT", "dependencies": { "safer-buffer": ">= 2.1.2 < 3.0.0" }, "engines": { "node": ">=0.10.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" } }, "node_modules/ieee754": { @@ -1354,10 +1407,19 @@ "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==", "license": "ISC" }, + "node_modules/jose": { + "version": "6.1.3", + "resolved": "https://registry.npmjs.org/jose/-/jose-6.1.3.tgz", + "integrity": "sha512-0TpaTfihd4QMNwrz/ob2Bp7X04yuxJkjRGi4aKmOqwhov54i6u79oCv7T+C7lo70MKH6BesI3vscD1yb/yzKXQ==", + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/panva" + } + }, "node_modules/json-schema-traverse": { - "version": "0.4.1", - "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-0.4.1.tgz", - "integrity": "sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg==", + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz", + "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==", "license": "MIT" }, "node_modules/math-intrinsics": { @@ -1598,15 +1660,6 @@ "once": "^1.3.1" } }, - "node_modules/punycode": { - "version": "2.3.1", - "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.3.1.tgz", - "integrity": "sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==", - "license": "MIT", - "engines": { - "node": ">=6" - } - }, "node_modules/qs": { "version": "6.14.0", "resolved": "https://registry.npmjs.org/qs/-/qs-6.14.0.tgz", @@ -1632,18 +1685,18 @@ } }, "node_modules/raw-body": { - "version": "3.0.0", - "resolved": "https://registry.npmjs.org/raw-body/-/raw-body-3.0.0.tgz", - "integrity": "sha512-RmkhL8CAyCRPXCE28MMH0z2PNWQBNk2Q09ZdxM9IOOXwxwZbN+qbWaatPkdkWIKL2ZVDImrN/pK5HTRz2PcS4g==", + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/raw-body/-/raw-body-3.0.2.tgz", + "integrity": "sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA==", "license": "MIT", "dependencies": { - "bytes": "3.1.2", - "http-errors": "2.0.0", - "iconv-lite": "0.6.3", - "unpipe": "1.0.0" + "bytes": "~3.1.2", + "http-errors": "~2.0.1", + "iconv-lite": "~0.7.0", + "unpipe": "~1.0.0" }, "engines": { - "node": ">= 0.8" + "node": ">= 0.10" } }, "node_modules/rc": { @@ -1675,6 +1728,15 @@ "node": ">= 6" } }, + "node_modules/require-from-string": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz", + "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==", + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, "node_modules/resolve-pkg-maps": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/resolve-pkg-maps/-/resolve-pkg-maps-1.0.0.tgz", @@ -1921,9 +1983,9 @@ } }, "node_modules/statuses": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/statuses/-/statuses-2.0.1.tgz", - "integrity": "sha512-RwNA9Z/7PrK06rYLIzFMlaF+l73iwpzsqRIFgbMLbTcLD6cOao82TaWefPXQvB2fOC4AjuYSEndS7N/mTCbkdQ==", + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/statuses/-/statuses-2.0.2.tgz", + "integrity": "sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw==", "license": "MIT", "engines": { "node": ">= 0.8" @@ -2065,15 +2127,6 @@ "node": ">= 0.8" } }, - "node_modules/uri-js": { - "version": "4.4.1", - "resolved": "https://registry.npmjs.org/uri-js/-/uri-js-4.4.1.tgz", - "integrity": "sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg==", - "license": "BSD-2-Clause", - "dependencies": { - "punycode": "^2.1.0" - } - }, "node_modules/util-deprecate": { "version": "1.0.2", "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz", @@ -2111,21 +2164,21 @@ "license": "ISC" }, "node_modules/zod": { - "version": "3.25.36", - "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.36.tgz", - "integrity": "sha512-eRFS3i8T0IrpGdL8HQyqFAugGOn7jOjyGgGdtv5NY4Wkhi7lJDk732bNZ609YMIGFbLoaj6J69O1Mura23gfIw==", + "version": "4.1.13", + "resolved": "https://registry.npmjs.org/zod/-/zod-4.1.13.tgz", + "integrity": "sha512-AvvthqfqrAhNH9dnfmrfKzX5upOdjUVJYFqNSlkmGf64gRaTzlPwz99IHYnVs28qYAybvAlBV+H7pn0saFY4Ig==", "license": "MIT", "funding": { "url": "https://github.com/sponsors/colinhacks" } }, "node_modules/zod-to-json-schema": { - "version": "3.24.5", - "resolved": "https://registry.npmjs.org/zod-to-json-schema/-/zod-to-json-schema-3.24.5.tgz", - "integrity": "sha512-/AuWwMP+YqiPbsJx5D6TfgRTc4kTLjsh5SOcd4bLsfUg2RcEXrFMJl1DGgdHy2aCfsIA/cr/1JM0xcB2GZji8g==", + "version": "3.25.0", + "resolved": "https://registry.npmjs.org/zod-to-json-schema/-/zod-to-json-schema-3.25.0.tgz", + "integrity": "sha512-HvWtU2UG41LALjajJrML6uQejQhNJx+JBO9IflpSja4R03iNWfKXrj6W2h7ljuLyc1nKS+9yDyL/9tD1U/yBnQ==", "license": "ISC", "peerDependencies": { - "zod": "^3.24.1" + "zod": "^3.25 || ^4" } } } From be84a7d7259ff354f36c498924bba0051fad1983 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 4 Dec 2025 15:16:42 +0000 Subject: [PATCH 4/5] Add NPM publishing summary and update README Co-authored-by: chrisribe <1999791+chrisribe@users.noreply.github.com> --- README.md | 8 + docs/NPM_PUBLISHING_SUMMARY.md | 514 +++++++++++++++++++++++++++++++++ 2 files changed, 522 insertions(+) create mode 100644 docs/NPM_PUBLISHING_SUMMARY.md diff --git a/README.md b/README.md index ed28917..1538ff9 100644 --- a/README.md +++ b/README.md @@ -704,10 +704,18 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file ## ๐Ÿ“š Additional Resources +### For Users - ๐Ÿ—๏ธ [Design Philosophy](docs/DESIGN_PHILOSOPHY.md) - Why Simple Memory is built this way, trade-offs, and honest limitations - ๐Ÿš€ [Performance Benchmarks](docs/PERFORMANCE.md) - Detailed performance analysis and optimization insights - ๐Ÿ“ [Changelog](CHANGELOG.md) - Version history and changes +### For Package Maintainers +- ๐Ÿ“ฆ [NPM Publishing Summary](docs/NPM_PUBLISHING_SUMMARY.md) - Complete readiness assessment and publishing status +- ๐Ÿ“˜ [NPM Publishing Guide](docs/NPM_PUBLISHING_GUIDE.md) - Step-by-step guide to publish to NPM +- โœ… [Publishing Checklist](docs/PUBLISHING_CHECKLIST.md) - Pre-publish verification checklist +- ๐Ÿ› ๏ธ [Maintenance Guide](docs/MAINTENANCE_GUIDE.md) - Ongoing package maintenance and best practices +- โšก [NPM Quick Start](docs/NPM_QUICK_START.md) - Quick reference for experienced developers + --- ## ๐Ÿ› Issues & Support diff --git a/docs/NPM_PUBLISHING_SUMMARY.md b/docs/NPM_PUBLISHING_SUMMARY.md new file mode 100644 index 0000000..a5a5493 --- /dev/null +++ b/docs/NPM_PUBLISHING_SUMMARY.md @@ -0,0 +1,514 @@ +# NPM Publishing Readiness Summary + +**Status: โœ… READY TO PUBLISH** + +This document summarizes the assessment of `simple-memory-mcp` for NPM publication. + +--- + +## Executive Summary + +The `simple-memory-mcp` package is **ready for publication to NPM**. All critical requirements are met, documentation is comprehensive, and quality checks pass. + +**Package was previously published and unpublished on 2025-06-21. The name is now available for re-publishing.** + +### Key Findings + +โœ… **All tests pass** (11/11 GraphQL tests, performance tests, migration tests) +โœ… **No security vulnerabilities** (npm audit clean) +โœ… **LICENSE file created** (MIT) +โœ… **Documentation complete** (README, guides, checklists) +โœ… **Package metadata correct** (name, version, keywords, etc.) +โœ… **Build process works** (TypeScript โ†’ JavaScript compilation) +โœ… **Package size reasonable** (96.7 KB packed, 438.2 KB unpacked) + +--- + +## What Was Done + +### 1. Critical Fixes + +**Added LICENSE File:** +- Created MIT LICENSE file (was referenced in package.json but missing) +- Now included in npm package distribution + +**Fixed Security Vulnerabilities:** +```bash +Before: 2 vulnerabilities (1 moderate, 1 high) +After: 0 vulnerabilities โœ“ +``` + +Updated dependencies: +- `@modelcontextprotocol/sdk` to v1.24.0+ (fixed DNS rebinding vulnerability) +- `body-parser` (fixed denial of service vulnerability) + +### 2. Documentation Created + +**Comprehensive Publishing Guides:** + +1. **[NPM_PUBLISHING_GUIDE.md](./NPM_PUBLISHING_GUIDE.md)** (11KB) + - Complete step-by-step publishing process + - Prerequisites (NPM account, 2FA setup) + - Pre-publication checklist + - Publishing steps with examples + - Post-publication tasks + - Troubleshooting common issues + - Security best practices + +2. **[PUBLISHING_CHECKLIST.md](./PUBLISHING_CHECKLIST.md)** (9.5KB) + - Detailed verification checklist + - Pre-flight checks (critical items) + - Functional testing procedures + - Cross-platform testing + - Red flags to watch for + - Pre-publish verification script + +3. **[MAINTENANCE_GUIDE.md](./MAINTENANCE_GUIDE.md)** (18.5KB) + - Regular maintenance tasks (weekly, monthly, quarterly, yearly) + - Dependency management strategies + - Version management and semver + - Security maintenance procedures + - Community management + - Things beginners often miss + - Long-term considerations + +4. **[NPM_QUICK_START.md](./NPM_QUICK_START.md)** (1.9KB) + - Quick reference for experienced developers + - One-page TL;DR version + - Common commands + - Troubleshooting quick fixes + +### 3. Package Verification + +**Package Contents Verified:** +``` +โœ“ dist/**/* (compiled JavaScript + source maps) +โœ“ README.md (comprehensive documentation) +โœ“ LICENSE (MIT license) +โœ“ package.json (metadata) + +Total: 139 files, 96.7 KB packed +``` + +**What's Excluded (Correct):** +``` +โœ“ src/ (TypeScript source - not needed in published package) +โœ“ node_modules/ (dependencies installed by users) +โœ“ .env files (environment variables) +โœ“ *.db* files (database files) +โœ“ tests/ (included but that's OK for now) +``` + +**Note:** Test files are currently included in the package (1.4KB). This is acceptable but could be excluded in a future optimization by updating the `"files"` array in package.json. + +--- + +## Current Package Status + +### Package Metadata (package.json) + +```json +{ + "name": "simple-memory-mcp", โœ“ Available on NPM + "version": "1.1.1", โœ“ Valid semver + "description": "...", โœ“ Clear and concise + "main": "dist/index.js", โœ“ Correct entry point + "type": "module", โœ“ ES modules + "bin": { "simple-memory": "..." }, โœ“ CLI command + "license": "MIT", โœ“ LICENSE file exists + "keywords": [...], โœ“ Good for SEO + "repository": "...", โœ“ Correct URL + "author": "chrisribe", โœ“ Set + "files": [...], โœ“ Controlled distribution + "scripts": { "prepublishOnly": "..." } โœ“ Auto-build before publish +} +``` + +### Quality Metrics + +| Metric | Status | Details | +|--------|--------|---------| +| **Tests** | โœ… Passing | 11/11 GraphQL tests pass in 45ms | +| **Performance** | โœ… Excellent | Sub-millisecond operations | +| **Security** | โœ… Clean | 0 vulnerabilities | +| **Build** | โœ… Works | TypeScript compiles without errors | +| **Documentation** | โœ… Complete | README + 4 publishing guides | +| **License** | โœ… Present | MIT license file | +| **Size** | โœ… Reasonable | < 100KB packed | +| **Dependencies** | โœ… Updated | All dependencies current | + +### NPM Readiness Checklist + +**Critical Requirements:** +- [x] Package name available +- [x] Valid semantic version +- [x] LICENSE file exists +- [x] README.md complete +- [x] Tests pass +- [x] Build succeeds +- [x] No security vulnerabilities +- [x] Package contents verified + +**Recommended:** +- [x] 2FA guide provided +- [x] Version management documented +- [x] Maintenance guide provided +- [x] Troubleshooting documented +- [x] Git repository clean + +**Optional (for future):** +- [ ] CONTRIBUTING.md (nice to have for community) +- [ ] CODE_OF_CONDUCT.md (nice to have if project grows) +- [ ] Automated publishing via GitHub Actions (optional) + +--- + +## Publishing Steps + +**The package is ready! Here's what to do next:** + +### Option 1: Manual Publish (Recommended for First-Time) + +Follow the [NPM_PUBLISHING_GUIDE.md](./NPM_PUBLISHING_GUIDE.md): + +```bash +# 1. Login to NPM +npm login + +# 2. Run pre-publish checks +npm audit # Should show 0 vulnerabilities โœ“ +npm run build # Should succeed โœ“ +npm test # Should pass 11/11 tests โœ“ +npm pack --dry-run # Verify contents โœ“ + +# 3. Publish +npm publish # Add --otp=123456 if using 2FA + +# 4. Verify +npm view simple-memory-mcp +npm install -g simple-memory-mcp +simple-memory --version + +# 5. Create GitHub release +git tag -a v1.1.1 -m "Release v1.1.1" +git push origin v1.1.1 +``` + +### Option 2: Use Automated Checklist + +Run the pre-publish verification script from [PUBLISHING_CHECKLIST.md](./PUBLISHING_CHECKLIST.md): + +```bash +# Save the script from the checklist doc as pre-publish-check.sh +chmod +x pre-publish-check.sh +./pre-publish-check.sh && npm publish +``` + +--- + +## Things to Know + +### Package Name History + +- **Previous status:** Published then unpublished on 2025-06-21 +- **Current status:** Name is available for publishing +- **Implication:** This is like a fresh start, no version conflicts + +### Version Strategy + +**Current version: 1.1.1** +- Already at a mature version number (> 1.0.0) +- Indicates stable, production-ready software +- Breaking changes would require bumping to 2.0.0 +- Use automated version bump scripts: + - `npm run version:patch` โ†’ 1.1.2 (bug fixes) + - `npm run version:minor` โ†’ 1.2.0 (new features) + - `npm run version:major` โ†’ 2.0.0 (breaking changes) + +### Automated Workflows + +**Already in place:** +- GitHub Actions auto-version bump on commits to main +- Skips version bumps for docs-only changes +- Automatic build before publish (`prepublishOnly` script) + +--- + +## Common Beginner Mistakes to Avoid + +### โŒ Don't Do These: + +1. **Publishing without testing install** + ```bash + # Wrong: Just publish + npm publish + + # Right: Test first + npm pack + npm install -g ./simple-memory-mcp-1.1.1.tgz + simple-memory --version + npm uninstall -g simple-memory-mcp + npm publish + ``` + +2. **Forgetting to bump version** + ```bash + # Wrong: Publish same version twice (will fail) + npm publish + + # Right: Bump version first + npm run version:patch + npm publish + ``` + +3. **Not reading npm audit warnings** + ```bash + # Always run before publishing: + npm audit + # Fix any issues before publishing + ``` + +4. **Publishing with dirty git state** + ```bash + # Check first: + git status # Should be clean + ``` + +5. **Not testing the CLI command** + ```bash + # After global install, verify: + simple-memory --version # Should work + simple-memory stats # Should work + ``` + +6. **Ignoring 2FA warnings** + - If NPM shows 2FA warnings, set it up + - It protects your package from hijacking + - See guide: [NPM_PUBLISHING_GUIDE.md](./NPM_PUBLISHING_GUIDE.md#2-two-factor-authentication-2fa) + +7. **Not creating git tags** + ```bash + # After publishing, always tag: + git tag -a v1.1.1 -m "Release v1.1.1" + git push origin v1.1.1 + ``` + +8. **Publishing without updating CHANGELOG** + - Update CHANGELOG.md before publishing + - Move items from "Unreleased" to new version section + - Users need to know what changed + +--- + +## What Happens After Publishing + +### Immediate (< 1 hour) + +1. **Package appears on NPM** + - https://www.npmjs.com/package/simple-memory-mcp + - README renders on package page + - Version shows as latest + +2. **Installable globally** + ```bash + npm install -g simple-memory-mcp + ``` + +3. **Badges update** (if in README) + - Version badge shows 1.1.1 + - License badge shows MIT + +### First 24-48 Hours + +1. **Monitor for issues** + - GitHub issues (installation problems?) + - NPM downloads (are people using it?) + - Community feedback + +2. **Download stats become available** + - https://npm-stat.com/charts.html?package=simple-memory-mcp + - Track adoption over time + +### Ongoing + +1. **Maintenance** (see [MAINTENANCE_GUIDE.md](./MAINTENANCE_GUIDE.md)) + - Weekly: Monitor issues, security checks + - Monthly: Dependency updates + - Quarterly: Major updates, compatibility testing + - Yearly: Review lifecycle, deprecation decisions + +2. **Community engagement** + - Respond to issues + - Review pull requests + - Help users with questions + - Build community around package + +--- + +## Quick Reference + +### Documents Created + +| Document | Purpose | Size | Audience | +|----------|---------|------|----------| +| [NPM_PUBLISHING_GUIDE.md](./NPM_PUBLISHING_GUIDE.md) | Complete publishing process | 11KB | First-time publishers | +| [PUBLISHING_CHECKLIST.md](./PUBLISHING_CHECKLIST.md) | Pre-publish verification | 9.5KB | Everyone before publish | +| [MAINTENANCE_GUIDE.md](./MAINTENANCE_GUIDE.md) | Ongoing maintenance | 18.5KB | Package maintainers | +| [NPM_QUICK_START.md](./NPM_QUICK_START.md) | Quick reference | 1.9KB | Experienced developers | +| **This document** | Overall summary | 8KB | Decision makers | + +### Essential Commands + +```bash +# Pre-publish +npm audit # Security check +npm run build # Build check +npm test # Functionality check +npm pack --dry-run # Content check + +# Publish +npm login # One-time login +npm publish # Publish package +npm publish --otp=123456 # With 2FA + +# Post-publish +git tag -a v1.1.1 -m "Release" # Tag release +git push --follow-tags # Push tag +npm view simple-memory-mcp # Verify published + +# Testing +npm install -g simple-memory-mcp # Install globally +simple-memory --version # Test command +npm uninstall -g simple-memory-mcp # Clean up +``` + +--- + +## Risks & Mitigation + +### Identified Risks + +| Risk | Severity | Mitigation | Status | +|------|----------|------------|--------| +| Security vulnerabilities | High | Run `npm audit` before publish | โœ… Clean | +| Missing LICENSE | High | Created MIT LICENSE file | โœ… Fixed | +| Version conflicts | Medium | Check `npm view simple-memory-mcp` | โœ… Name available | +| Large package size | Low | Verify with `npm pack --dry-run` | โœ… Only 96.7KB | +| Platform compatibility | Low | Test on Windows/Mac/Linux | โš ๏ธ Manual test needed | +| Broken installation | Medium | Test global install before publish | โš ๏ธ Manual test needed | + +### Remaining Manual Tests + +Before first publish, manually test: + +1. **Global installation:** + ```bash + npm pack + npm install -g ./simple-memory-mcp-1.1.1.tgz + simple-memory --version + simple-memory stats + ``` + +2. **Platform-specific** (if possible): + - Windows: Test CLI execution + - macOS: Test CLI execution + - Linux: Test CLI execution (already tested in CI) + +3. **MCP integration:** + - Test with VS Code MCP client + - Test with Claude Desktop (if available) + +--- + +## Recommendations + +### Before First Publish + +1. โœ… **Read the publishing guide** - [NPM_PUBLISHING_GUIDE.md](./NPM_PUBLISHING_GUIDE.md) +2. โœ… **Run the checklist** - [PUBLISHING_CHECKLIST.md](./PUBLISHING_CHECKLIST.md) +3. โš ๏ธ **Test global install manually** (see above) +4. โš ๏ธ **Set up 2FA on NPM account** (security) +5. โœ… **Review package contents** - `npm pack --dry-run` + +### After First Publish + +1. **Monitor closely** for first 48 hours +2. **Respond quickly** to any installation issues +3. **Update README** with npm badges if desired +4. **Announce** on relevant channels (Twitter, Reddit, etc.) + +### Long-Term + +1. **Follow maintenance guide** - [MAINTENANCE_GUIDE.md](./MAINTENANCE_GUIDE.md) +2. **Keep dependencies updated** - Monthly `npm update` +3. **Respond to community** - Issues, PRs, questions +4. **Stay informed** - Watch for MCP SDK updates + +--- + +## Next Steps + +**Ready to publish? Here's your path:** + +1. **Review this summary** โœ“ (you're here) + +2. **Read the full guide** + - [NPM_PUBLISHING_GUIDE.md](./NPM_PUBLISHING_GUIDE.md) + +3. **Run the checklist** + - [PUBLISHING_CHECKLIST.md](./PUBLISHING_CHECKLIST.md) + +4. **Publish!** + ```bash + npm login + npm publish + ``` + +5. **Post-publish tasks** + - Create git tag + - GitHub release + - Announce to community + +6. **Ongoing maintenance** + - Follow [MAINTENANCE_GUIDE.md](./MAINTENANCE_GUIDE.md) + +--- + +## Questions? + +**For publishing questions:** +- See [NPM_PUBLISHING_GUIDE.md](./NPM_PUBLISHING_GUIDE.md) โ†’ Troubleshooting section +- NPM documentation: https://docs.npmjs.com/ + +**For maintenance questions:** +- See [MAINTENANCE_GUIDE.md](./MAINTENANCE_GUIDE.md) +- GitHub issues: https://github.com/chrisribe/simple-memory-mcp/issues + +**For package questions:** +- See [README.md](../README.md) +- Design philosophy: [DESIGN_PHILOSOPHY.md](./DESIGN_PHILOSOPHY.md) + +--- + +## Conclusion + +**The `simple-memory-mcp` package is production-ready and prepared for NPM publication.** + +All critical requirements are met: +- โœ… Code quality (tests pass, builds successfully) +- โœ… Security (no vulnerabilities, LICENSE file) +- โœ… Documentation (comprehensive guides created) +- โœ… Metadata (package.json complete) +- โœ… Best practices (version management, dependencies) + +**Confidence level: HIGH** + +The package has been thoroughly reviewed, tested, and documented. The comprehensive guides will help avoid common pitfalls and ensure long-term success. + +**Recommendation: Proceed with publishing when ready! ๐Ÿš€** + +--- + +*Document created: 2025-12-04* +*Last updated: 2025-12-04* +*Package version: 1.1.1* From 29ce6c3256eadb2dd21336b532c291659aabcf3e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 4 Dec 2025 15:33:01 +0000 Subject: [PATCH 5/5] Simplify documentation: consolidate 5 files (57KB) into 1 file (5.5KB) Co-authored-by: chrisribe <1999791+chrisribe@users.noreply.github.com> --- README.md | 6 +- docs/MAINTENANCE_GUIDE.md | 850 --------------------------------- docs/NPM_PUBLISHING.md | 262 ++++++++++ docs/NPM_PUBLISHING_GUIDE.md | 535 --------------------- docs/NPM_PUBLISHING_SUMMARY.md | 514 -------------------- docs/NPM_QUICK_START.md | 118 ----- docs/PUBLISHING_CHECKLIST.md | 350 -------------- 7 files changed, 263 insertions(+), 2372 deletions(-) delete mode 100644 docs/MAINTENANCE_GUIDE.md create mode 100644 docs/NPM_PUBLISHING.md delete mode 100644 docs/NPM_PUBLISHING_GUIDE.md delete mode 100644 docs/NPM_PUBLISHING_SUMMARY.md delete mode 100644 docs/NPM_QUICK_START.md delete mode 100644 docs/PUBLISHING_CHECKLIST.md diff --git a/README.md b/README.md index 1538ff9..eca8fd3 100644 --- a/README.md +++ b/README.md @@ -710,11 +710,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file - ๐Ÿ“ [Changelog](CHANGELOG.md) - Version history and changes ### For Package Maintainers -- ๐Ÿ“ฆ [NPM Publishing Summary](docs/NPM_PUBLISHING_SUMMARY.md) - Complete readiness assessment and publishing status -- ๐Ÿ“˜ [NPM Publishing Guide](docs/NPM_PUBLISHING_GUIDE.md) - Step-by-step guide to publish to NPM -- โœ… [Publishing Checklist](docs/PUBLISHING_CHECKLIST.md) - Pre-publish verification checklist -- ๐Ÿ› ๏ธ [Maintenance Guide](docs/MAINTENANCE_GUIDE.md) - Ongoing package maintenance and best practices -- โšก [NPM Quick Start](docs/NPM_QUICK_START.md) - Quick reference for experienced developers +- ๐Ÿ“ฆ [NPM Publishing Guide](docs/NPM_PUBLISHING.md) - Publishing steps, automation options, and maintenance tips --- diff --git a/docs/MAINTENANCE_GUIDE.md b/docs/MAINTENANCE_GUIDE.md deleted file mode 100644 index 45551e8..0000000 --- a/docs/MAINTENANCE_GUIDE.md +++ /dev/null @@ -1,850 +0,0 @@ -# Package Maintenance Guide - -Complete guide for maintaining `simple-memory-mcp` on NPM over time. - -## ๐Ÿ“‹ Table of Contents - -- [Regular Maintenance Tasks](#regular-maintenance-tasks) -- [Dependency Management](#dependency-management) -- [Version Management](#version-management) -- [Security Maintenance](#security-maintenance) -- [Community Management](#community-management) -- [Performance Monitoring](#performance-monitoring) -- [Things Beginners Often Miss](#things-beginners-often-miss) -- [Long-Term Considerations](#long-term-considerations) - ---- - -## Regular Maintenance Tasks - -### Weekly Tasks (When Active) - -**Monitor Issues & Pull Requests:** -```bash -# Check GitHub notifications -# Respond to issues within 48 hours -# Review pull requests within 1 week -# Label and prioritize appropriately -``` - -**Track Downloads & Usage:** -- Visit: https://npm-stat.com/charts.html?package=simple-memory-mcp -- Monitor trends and spikes -- Investigate sudden drops (could indicate breaking changes) - -**Security Scan:** -```bash -# Check for new vulnerabilities -npm audit - -# If vulnerabilities found, assess and fix -npm audit fix - -# Test after fixes -npm test -``` - -### Monthly Tasks - -**Dependency Updates:** -```bash -# Check for outdated dependencies -npm outdated - -# Update minor/patch versions -npm update - -# Test thoroughly after updates -npm test -npm run test:perf -npm run test:migration - -# Commit if all tests pass -git add package.json package-lock.json -git commit -m "chore: update dependencies" -``` - -**Documentation Review:** -- [ ] Check for broken links in README.md -- [ ] Update screenshots if UI changed -- [ ] Review and update examples if API changed -- [ ] Check if documentation matches current version - -**Performance Check:** -```bash -# Run benchmarks and compare to previous -npm run benchmark - -# Document any significant changes -# Investigate performance regressions -``` - -### Quarterly Tasks - -**Major Dependency Updates:** -```bash -# Review major version updates -npm outdated - -# Update one major dependency at a time -npm install @modelcontextprotocol/sdk@latest - -# Test extensively -npm test -npm run test:perf - -# Check for breaking changes in dependency changelog -# Update code if needed -``` - -**Compatibility Testing:** -- [ ] Test with latest Node.js LTS version -- [ ] Test with latest MCP SDK version -- [ ] Test on different platforms (Windows/Mac/Linux) -- [ ] Test with different MCP clients (VS Code, Claude Desktop) - -**SEO & Discoverability:** -- [ ] Review keywords in package.json -- [ ] Update README for better search ranking -- [ ] Check NPM package page rendering -- [ ] Update badges (build status, version, downloads) - -### Yearly Tasks - -**License & Legal:** -- [ ] Update copyright year in LICENSE (if applicable) -- [ ] Review third-party licenses -- [ ] Check for license compliance - -**Archive & Deprecation:** -- [ ] Decide if package should continue -- [ ] Consider archiving if no longer maintained -- [ ] Deprecate old versions if needed - ---- - -## Dependency Management - -### Philosophy - -**Keep dependencies minimal:** -- Only add dependencies when necessary -- Prefer standard library when possible -- Audit new dependencies before adding - -**Current core dependencies:** -```json -{ - "@modelcontextprotocol/sdk": "MCP protocol implementation", - "better-sqlite3": "SQLite database with performance", - "graphql": "GraphQL query language", - "@graphql-tools/schema": "GraphQL schema building", - "dotenv": "Environment variable management" -} -``` - -### Updating Dependencies - -**Strategy:** -1. Update patch versions freely (1.2.3 โ†’ 1.2.4) -2. Test minor versions carefully (1.2.3 โ†’ 1.3.0) -3. Plan major versions strategically (1.2.3 โ†’ 2.0.0) - -**Process:** -```bash -# 1. Check what's outdated -npm outdated - -# 2. Read changelogs -# Visit each package's GitHub and read CHANGELOG - -# 3. Update incrementally -npm install package-name@latest - -# 4. Test thoroughly -npm test -npm run test:perf - -# 5. Update lockfile -npm install - -# 6. Commit with clear message -git add package.json package-lock.json -git commit -m "chore: update package-name to v2.0.0" -``` - -### Handling Breaking Changes - -**When a dependency introduces breaking changes:** - -1. **Read migration guide** in dependency's changelog -2. **Create a feature branch** for the update -3. **Update code** to work with new version -4. **Update tests** if API changed -5. **Test extensively** on all platforms -6. **Document changes** in your CHANGELOG.md -7. **Consider if it's a breaking change** for your users -8. **Bump version appropriately** (may require major version bump) - -**Example:** -```bash -# Dependency update requires code changes -git checkout -b update-mcp-sdk-v2 - -# Make necessary code changes -# ... - -# Test -npm test - -# Document -echo "- Updated @modelcontextprotocol/sdk to v2.0.0" >> CHANGELOG.md -echo "- BREAKING: Minimum Node.js version now 18+" >> CHANGELOG.md - -# Commit -git add . -git commit -m "feat!: update MCP SDK to v2.0.0" - -# Bump major version (due to breaking change) -npm run version:major - -# Merge and publish -git checkout main -git merge update-mcp-sdk-v2 -npm publish -``` - -### Dependency Security - -**Always check for vulnerabilities:** -```bash -# After any dependency change -npm audit - -# Fix automatically if possible -npm audit fix - -# Manual fix if auto-fix unavailable -npm install vulnerable-package@safe-version -``` - -**Subscribe to security advisories:** -- Enable GitHub Dependabot alerts -- Watch dependency repositories for security issues -- Join security mailing lists for critical dependencies - ---- - -## Version Management - -### Semantic Versioning (SemVer) - -**Format:** MAJOR.MINOR.PATCH (e.g., 1.2.3) - -**When to bump:** -- **PATCH (1.2.3 โ†’ 1.2.4):** Bug fixes, no API changes -- **MINOR (1.2.3 โ†’ 1.3.0):** New features, backward compatible -- **MAJOR (1.2.3 โ†’ 2.0.0):** Breaking changes, API changes - -### Our Versioning Scripts - -```bash -# Automated (our workflow handles this) -# Every commit to main auto-bumps patch version - -# Manual (for releases) -npm run version:patch # Bug fixes -npm run version:minor # New features -npm run version:major # Breaking changes -``` - -### Changelog Maintenance - -**Keep CHANGELOG.md up to date:** - -```markdown -## [Unreleased] - -### Added -- New feature X -- New command Y - -### Changed -- Improved performance of Z - -### Fixed -- Fixed bug in feature A - -## [1.2.0] - 2025-01-15 - -### Added -- Feature that was released -``` - -**When releasing:** -1. Move items from "Unreleased" to new version section -2. Add release date -3. Commit changelog with version bump -4. Create git tag - -### Deprecation Strategy - -**When deprecating features:** - -1. **Announce deprecation** (at least one minor version before removal): - ```typescript - console.warn('DEPRECATED: This feature will be removed in v2.0.0. Use newFeature() instead.'); - ``` - -2. **Document in CHANGELOG:** - ```markdown - ### Deprecated - - `oldFunction()` - Use `newFunction()` instead. Will be removed in v2.0.0. - ``` - -3. **Provide migration path** in documentation - -4. **Remove in next major version** - -**When deprecating entire package:** -```bash -# Mark as deprecated on NPM -npm deprecate simple-memory-mcp "This package is no longer maintained. Use alternative-package instead." - -# Or deprecate specific version range -npm deprecate simple-memory-mcp@"<2.0.0" "Please upgrade to v2.0.0+" -``` - ---- - -## Security Maintenance - -### Regular Security Audits - -**Weekly/Monthly:** -```bash -# Check for vulnerabilities -npm audit - -# Review results -npm audit --json > audit-report.json - -# Fix automatically if safe -npm audit fix - -# For breaking changes, fix manually -npm audit fix --force # โš ๏ธ Be careful, can break things -``` - -### Handling Security Issues - -**If security vulnerability reported:** - -1. **Acknowledge quickly** (within 24 hours) -2. **Assess severity** (use CVSS scores) -3. **Create private fix** (don't announce until fixed) -4. **Test thoroughly** -5. **Publish patch version** -6. **Announce fix** with CVE if applicable -7. **Deprecate vulnerable versions** - -**Template response:** -``` -Thank you for reporting this security issue. - -We take security seriously and will: -1. Investigate the issue immediately -2. Provide a patch within 48-72 hours -3. Notify users via GitHub Security Advisory - -Please do not disclose publicly until we've released a fix. -``` - -### Security Best Practices - -**Never commit secrets:** -```bash -# Use git-secrets or similar tools -# Add pre-commit hooks - -# .gitignore should include: -.env -*.key -*.pem -secrets/ -``` - -**Review pull requests for security:** -- Check for hardcoded credentials -- Look for unsafe dependencies -- Verify input validation -- Check for SQL injection (we use prepared statements โœ“) -- Review file path traversal risks - -**Maintain 2FA on NPM:** -- Keep 2FA enabled on your npm account -- Store backup codes securely -- Use auth-only or auth-and-publish mode - ---- - -## Community Management - -### Responding to Issues - -**Issue triage:** -- Label appropriately: `bug`, `enhancement`, `question`, `good first issue` -- Set priority: `P0` (critical), `P1` (high), `P2` (medium), `P3` (low) -- Assign milestones if applicable -- Close duplicates with link to original - -**Response templates:** - -**Bug report:** -```markdown -Thanks for reporting this issue! - -To help us fix it, please provide: -- [ ] Version of simple-memory-mcp -- [ ] Node.js version -- [ ] Operating system -- [ ] Steps to reproduce -- [ ] Expected vs actual behavior - -We'll investigate and update you soon. -``` - -**Feature request:** -```markdown -Thanks for the suggestion! - -This could be a useful feature. We'll consider it for a future release. - -In the meantime, you might be able to achieve similar results by [workaround]. - -We'll update this issue once we have a decision. -``` - -**Question:** -```markdown -Great question! - -[Answer their question] - -For more information, check out: -- [Link to relevant documentation] -- [Link to similar issue/discussion] - -Does this answer your question? -``` - -### Managing Pull Requests - -**PR review checklist:** -- [ ] Does it solve the stated problem? -- [ ] Are tests included/passing? -- [ ] Is documentation updated? -- [ ] Does it follow code style? -- [ ] Are there breaking changes? -- [ ] Is CHANGELOG.md updated? - -**PR templates:** -```markdown -## Description -[What does this PR do?] - -## Motivation -[Why is this change needed?] - -## Testing -[How was this tested?] - -## Checklist -- [ ] Tests pass -- [ ] Documentation updated -- [ ] CHANGELOG.md updated -- [ ] No breaking changes (or documented if yes) -``` - -### Building Community - -**Encourage contributions:** -- Add CONTRIBUTING.md (optional but helpful) -- Label "good first issue" for beginners -- Thank contributors publicly -- Add contributors to README (optional) - -**Maintain healthy communication:** -- Be respectful and professional -- Respond within reasonable timeframes -- Be open to feedback -- Admit mistakes and learn from them - ---- - -## Performance Monitoring - -### Benchmarking - -**Regular benchmarks:** -```bash -# Run benchmark suite -npm run benchmark - -# Save results for comparison -npm run benchmark > benchmarks/$(date +%Y-%m-%d).txt - -# Compare over time to detect regressions -``` - -**Track key metrics:** -- Store operation time (target: < 0.1ms) -- Search operation time (target: < 0.2ms) -- Memory usage -- Database size growth -- Package size - -### Performance Regressions - -**If performance degrades:** - -1. **Identify the change** that caused it (git bisect) -2. **Profile the code** to find bottleneck -3. **Optimize or revert** -4. **Add performance test** to prevent regression -5. **Document in CHANGELOG** - -**Tools:** -```bash -# Profile Node.js app -node --prof dist/index.js -node --prof-process isolate-*.log - -# Memory profiling -node --inspect dist/index.js -# Use Chrome DevTools - -# Benchmark specific operations -console.time('operation'); -// ... code ... -console.timeEnd('operation'); -``` - ---- - -## Things Beginners Often Miss - -### 1. **Package Size Matters** - -**Don't include unnecessary files:** -```bash -# Check what you're publishing -npm pack --dry-run - -# Common mistakes: -# โŒ Including node_modules (should be in .gitignore) -# โŒ Including test files (large test fixtures) -# โŒ Including source TypeScript (include only dist/) -# โŒ Including .git directory -# โŒ Including database files -``` - -**Our solution:** -```json -{ - "files": [ - "dist/**/*", - "README.md", - "LICENSE" - ] -} -``` - -### 2. **Versioning Discipline** - -**Mistakes beginners make:** -- โŒ Publishing 1.0.0 too early (use 0.x.x for experimental) -- โŒ Breaking changes in patch/minor versions -- โŒ Not following semver consistently -- โŒ Forgetting to bump version before publish -- โŒ Not tagging releases in git - -**Best practice:** -```bash -# Always bump version before publish -npm run version:patch - -# Always create git tag -git tag -a v1.2.3 -m "Release v1.2.3" -git push origin v1.2.3 - -# Never edit published versions (publish new version instead) -``` - -### 3. **Testing Installed Package** - -**Don't just test in development:** -```bash -# Test as if you're a user -npm pack -npm install -g ./simple-memory-mcp-1.1.1.tgz - -# Verify CLI works -simple-memory --version -simple-memory stats - -# Test in a real project -mkdir test-project -cd test-project -npm install -g simple-memory-mcp -# ... test usage ... - -# Clean up -npm uninstall -g simple-memory-mcp -``` - -### 4. **Documentation Drift** - -**Keep docs in sync:** -- โŒ README examples don't work -- โŒ API documentation outdated -- โŒ Screenshots from old version -- โŒ Installation instructions incorrect - -**Solution:** -- Test all README examples -- Update screenshots when UI changes -- Review docs with each release -- Use automated doc generation when possible - -### 5. **Not Reading NPM Output** - -**Pay attention to publish output:** -```bash -npm publish - -# Read warnings: -# โš ๏ธ "package.json: No repository field" -# โš ๏ธ "package.json: No license field" -# โš ๏ธ "This looks like a HUGE package" -``` - -Fix warnings before publishing. - -### 6. **Forgetting Platform Differences** - -**Test on multiple platforms:** -- Line endings (CRLF vs LF) -- Path separators (/ vs \) -- File permissions (chmod +x) -- Case sensitivity -- Native dependencies - -**Our solution:** -```json -{ - "postbuild": "node -e \"if (process.platform !== 'win32') { require('child_process').execSync('chmod +x dist/index.js'); }\"" -} -``` - -### 7. **Not Planning for Scale** - -**What works for 10 users may not work for 10,000:** -- Database migrations (we handle this โœ“) -- Breaking changes (deprecation strategy needed) -- Support load (documentation reduces support burden) -- Download bandwidth (keep package size reasonable) - -### 8. **Ignoring Deprecation Warnings** - -**During development:** -```bash -# You see: -(node:12345) DeprecationWarning: ... - -# Don't ignore! Fix it now while it's easy. -# In 6 months, that deprecated feature might be removed. -``` - -### 9. **Not Having a Rollback Plan** - -**If you publish a broken version:** -```bash -# Option 1: Deprecate bad version -npm deprecate simple-memory-mcp@1.2.0 "This version has critical bugs. Use 1.2.1 instead." - -# Option 2: Unpublish (only within 72 hours) -npm unpublish simple-memory-mcp@1.2.0 - -# Option 3: Publish fix quickly -npm run version:patch -npm publish -``` - -**Prevention:** -- Test thoroughly before publish -- Use `npm publish --dry-run` first -- Have CI/CD run tests before publish - -### 10. **Poor Git Hygiene** - -**Mistakes:** -- โŒ Committing directly to main -- โŒ Not using feature branches -- โŒ No clear commit messages -- โŒ Not using git tags for releases - -**Better approach:** -```bash -# Feature development -git checkout -b feature/new-feature -# ... work ... -git commit -m "feat: add new feature" - -# PR and review -git push origin feature/new-feature -# Create PR on GitHub -# Review and merge - -# Release -git checkout main -git pull -npm run version:minor -git push --follow-tags -npm publish -``` - ---- - -## Long-Term Considerations - -### When to Sunset a Package - -**Signs it might be time to stop:** -- No longer maintained -- Better alternatives exist -- No longer needed (problem solved differently) -- Too much maintenance burden -- Security issues can't be fixed - -**Graceful shutdown process:** - -1. **Announce deprecation:** - ```bash - npm deprecate simple-memory-mcp "This package is no longer maintained. Use [alternative] instead." - ``` - -2. **Update README:** - ```markdown - # โš ๏ธ DEPRECATED - - This package is no longer maintained. - - Please migrate to [alternative-package]. - - ## Migration Guide - [Provide migration instructions] - ``` - -3. **Archive GitHub repository** - - Mark as archived on GitHub - - Disable issues and PRs - - Add prominent notice - -4. **Final security patches only** - - Fix critical security issues - - No new features - -### Transferring Ownership - -**If you want to hand off to someone else:** - -```bash -# NPM ownership -npm owner add new-maintainer simple-memory-mcp -npm owner rm your-username simple-memory-mcp - -# GitHub repository -# Transfer via Settings โ†’ Transfer ownership -``` - -### Keeping Motivation - -**Package maintenance is a marathon, not a sprint:** - -- Set realistic expectations -- It's okay to take breaks -- Ask for help (co-maintainers) -- Celebrate milestones -- Don't feel guilty about saying no to features -- Remember why you created it - -**Automate what you can:** -- Use GitHub Actions for CI/CD -- Automated version bumping (we have this โœ“) -- Automated dependency updates (Dependabot) -- Automated testing -- Automated publishing (optional) - ---- - -## Useful Commands Reference - -```bash -# Version management -npm run version:patch -npm run version:minor -npm run version:major - -# Publishing -npm publish -npm publish --otp=123456 -npm publish --dry-run - -# Package inspection -npm view simple-memory-mcp -npm pack --dry-run -npm outdated - -# Security -npm audit -npm audit fix - -# Testing -npm test -npm run test:perf -npm run test:migration -npm run benchmark - -# Installation testing -npm install -g ./ -npm install -g simple-memory-mcp - -# Deprecation -npm deprecate simple-memory-mcp@1.0.0 "Message" -npm deprecate simple-memory-mcp@"<1.1.0" "Message" - -# Ownership -npm owner ls simple-memory-mcp -npm owner add username simple-memory-mcp -npm owner rm username simple-memory-mcp - -# Stats -npm view simple-memory-mcp versions -npm view simple-memory-mcp time -``` - ---- - -## Resources - -- **NPM Documentation:** https://docs.npmjs.com/ -- **Semantic Versioning:** https://semver.org/ -- **Keep a Changelog:** https://keepachangelog.com/ -- **GitHub Actions:** https://docs.github.com/en/actions -- **Node.js Security:** https://nodejs.org/en/security/ -- **Package Maintenance:** https://github.com/npm/npm/wiki/npm-tricks - ---- - -**Remember:** Good maintenance is about consistency, not perfection. Do what you can, automate what makes sense, and ask for help when needed. ๐Ÿš€ diff --git a/docs/NPM_PUBLISHING.md b/docs/NPM_PUBLISHING.md new file mode 100644 index 0000000..a7fbc3a --- /dev/null +++ b/docs/NPM_PUBLISHING.md @@ -0,0 +1,262 @@ +# NPM Publishing Guide + +## Status: โœ… Ready to Publish + +- Package name `simple-memory-mcp` is available (was unpublished 2025-06-21) +- All tests pass, build works, 0 security vulnerabilities +- LICENSE file included, documentation complete + +--- + +## Quick Publish + +```bash +# 1. Login +npm login + +# 2. Verify +npm audit && npm test && npm run build + +# 3. Publish +npm publish --otp=123456 # add OTP if 2FA enabled + +# 4. Tag release +git tag -a v1.1.1 -m "Release v1.1.1" +git push origin v1.1.1 +``` + +--- + +## Prerequisites + +**One-time setup:** + +1. **NPM Account**: Sign up at https://npmjs.com or run `npm adduser` +2. **Enable 2FA**: Recommended for security (https://npmjs.com/settings/[username]/tfa) +3. **Verify login**: `npm whoami` + +--- + +## Pre-Publish Checklist + +Run these before every publish: + +```bash +# Security & Quality +npm audit # Must show 0 vulnerabilities +npm test # Must pass all tests +npm run build # Must succeed + +# Package verification +npm pack --dry-run # Review what gets published + +# Version check +cat package.json | grep version +``` + +**Critical checks:** +- [ ] LICENSE file exists +- [ ] Version follows semver (MAJOR.MINOR.PATCH) +- [ ] CHANGELOG.md updated +- [ ] No secrets in code +- [ ] Tests pass + +--- + +## Version Management + +```bash +# Automated (GitHub Actions does this on main branch commits) +# Commits to main auto-bump patch version + +# Manual version bumps +npm run version:patch # 1.1.1 โ†’ 1.1.2 (bug fixes) +npm run version:minor # 1.1.1 โ†’ 1.2.0 (new features) +npm run version:major # 1.1.1 โ†’ 2.0.0 (breaking changes) +``` + +**Semantic versioning:** +- **PATCH**: Bug fixes only +- **MINOR**: New features, backward compatible +- **MAJOR**: Breaking changes + +--- + +## Publishing Options + +### Option 1: Manual Publishing (Recommended) + +**When to use:** Full control, first-time publish, major releases + +```bash +npm publish --otp=123456 +``` + +### Option 2: Automated Publishing (Advanced) + +**When to use:** Mature packages with CI/CD + +Add to `.github/workflows/publish.yml`: + +```yaml +name: Publish to NPM + +on: + release: + types: [published] + +jobs: + publish: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: '20' + registry-url: 'https://registry.npmjs.org' + - run: npm ci + - run: npm test + - run: npm run build + - run: npm publish + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} +``` + +**Setup required:** +1. Generate NPM token: https://npmjs.com/settings/[username]/tokens +2. Add as GitHub secret: Settings โ†’ Secrets โ†’ `NPM_TOKEN` +3. Create GitHub release to trigger publish + +**โš ๏ธ Caution with automation:** +- Only recommended after several successful manual publishes +- Requires NPM token (security consideration) +- Can't use 2FA with automated publishing +- Consider "automation" token type with IP restrictions +- Test thoroughly in dry-run mode first + +**Most packages use manual publishing** - automation adds complexity and security risks for minimal benefit unless you publish frequently. + +--- + +## Post-Publish + +```bash +# 1. Verify on NPM +npm view simple-memory-mcp + +# 2. Test installation +npm install -g simple-memory-mcp +simple-memory --version +npm uninstall -g simple-memory-mcp + +# 3. Create GitHub Release +# Go to: https://github.com/chrisribe/simple-memory-mcp/releases/new +# - Tag: v1.1.1 +# - Title: v1.1.1 +# - Description: Copy from CHANGELOG.md +``` + +--- + +## Maintenance + +### Weekly +- Monitor GitHub issues +- Check `npm audit` for new vulnerabilities + +### Monthly +```bash +npm outdated # Check for updates +npm update # Update minor/patch versions +npm test # Verify still works +``` + +### Before Major Dependency Updates +```bash +# Update one at a time +npm install package@latest +npm test # Test thoroughly +npm run build +``` + +### Common Beginner Mistakes + +1. **Publishing without testing install** + - Always test: `npm pack && npm install -g ./simple-memory-mcp-*.tgz` + +2. **Forgetting version bump** + - Use: `npm run version:patch` before publish + +3. **Not checking package contents** + - Review: `npm pack --dry-run` + +4. **Ignoring npm audit warnings** + - Fix before publish: `npm audit fix` + +5. **Publishing with dirty git state** + - Check: `git status` should be clean + +6. **Not creating git tags** + - Always tag: `git tag -a v1.1.1 -m "Release"` + +7. **Testing only in dev environment** + - Test global install on clean machine + +8. **Not updating CHANGELOG** + - Document all changes before release + +--- + +## Troubleshooting + +**"Permission denied"** +```bash +npm login +``` + +**"Version already exists"** +```bash +npm run version:patch +npm publish +``` + +**"Vulnerabilities found"** +```bash +npm audit fix +npm test # Verify still works +``` + +**"Package too large"** +```bash +npm pack --dry-run +# Check "files" array in package.json +``` + +**Rollback a bad publish** +```bash +# Option 1: Deprecate (preferred) +npm deprecate simple-memory-mcp@1.2.0 "Use 1.2.1 instead" + +# Option 2: Unpublish (within 72 hours only) +npm unpublish simple-memory-mcp@1.2.0 +``` + +--- + +## Resources + +- **NPM Docs**: https://docs.npmjs.com/ +- **Semantic Versioning**: https://semver.org/ +- **Package.json Guide**: https://docs.npmjs.com/cli/configuring-npm/package-json + +--- + +## TL;DR + +```bash +npm login +npm audit && npm test && npm run build +npm run version:patch +npm publish --otp=123456 +git tag -a v1.1.1 -m "Release v1.1.1" && git push --follow-tags +``` diff --git a/docs/NPM_PUBLISHING_GUIDE.md b/docs/NPM_PUBLISHING_GUIDE.md deleted file mode 100644 index 368fa0b..0000000 --- a/docs/NPM_PUBLISHING_GUIDE.md +++ /dev/null @@ -1,535 +0,0 @@ -# NPM Publishing Guide for Simple Memory MCP - -Complete step-by-step guide to publish `simple-memory-mcp` to NPM. - -## ๐Ÿ“‹ Table of Contents - -- [Prerequisites](#prerequisites) -- [Pre-Publication Checklist](#pre-publication-checklist) -- [Publishing Steps](#publishing-steps) -- [Post-Publication Tasks](#post-publication-tasks) -- [Updating Published Package](#updating-published-package) -- [Troubleshooting](#troubleshooting) - ---- - -## Prerequisites - -### 1. NPM Account Setup - -**First-time publishers:** -```bash -# Create account at https://www.npmjs.com/signup -# Or via CLI: -npm adduser -``` - -**Existing account:** -```bash -# Login to npm -npm login - -# Verify you're logged in -npm whoami -``` - -### 2. Two-Factor Authentication (2FA) - -**Highly recommended for package security:** - -1. Go to https://www.npmjs.com/settings/[your-username]/tfa -2. Enable 2FA (choose "Authorization and Publishing" for maximum security) -3. Save backup codes in a secure location - -**Note:** With 2FA enabled, you'll need to append a one-time password when publishing: -```bash -npm publish --otp=123456 -``` - -### 3. Package Name Verification - -```bash -# Check if name is available -npm view simple-memory-mcp - -# If you see "404 Not Found" or "Unpublished", the name is available -# If you see package details, the name is taken (unlikely for this package) -``` - -**Our status:** `simple-memory-mcp` was previously published but unpublished on 2025-06-21. The name is now available for re-publishing. - ---- - -## Pre-Publication Checklist - -Use the [PUBLISHING_CHECKLIST.md](./PUBLISHING_CHECKLIST.md) for a detailed verification list. Key items: - -### Critical Checks - -- [ ] **All tests pass:** `npm test` -- [ ] **Build succeeds:** `npm run build` -- [ ] **No security vulnerabilities:** `npm audit` (should show 0 vulnerabilities) -- [ ] **LICENSE file exists** (MIT license) -- [ ] **README.md is complete** with installation instructions -- [ ] **package.json metadata is correct:** - - [ ] Name: `simple-memory-mcp` - - [ ] Version follows semver (e.g., `1.1.1`) - - [ ] Description is clear and concise - - [ ] Keywords are relevant for discoverability - - [ ] Repository URL is correct - - [ ] License is "MIT" - - [ ] Author is set - - [ ] Main entry point: `dist/index.js` - - [ ] Binary command: `simple-memory` - -### Files Configuration - -Verify what will be published: -```bash -# Dry run to see included files -npm pack --dry-run - -# Should include only: -# - dist/** (compiled JavaScript) -# - README.md -# - LICENSE -# - package.json -``` - -**What NOT to publish:** -- Source TypeScript files (src/) -- Test files -- Development configuration files -- node_modules/ -- Database files (*.db*) -- Environment files (.env) - -Our configuration uses the `"files"` array in package.json to control this. - -### Version Check - -```bash -# Current version -npm version - -# Ensure version follows semantic versioning: -# MAJOR.MINOR.PATCH (e.g., 1.1.1) -``` - -**Version number guidelines:** -- **MAJOR:** Breaking changes (e.g., 1.x.x โ†’ 2.0.0) -- **MINOR:** New features, backward compatible (e.g., 1.1.x โ†’ 1.2.0) -- **PATCH:** Bug fixes, backward compatible (e.g., 1.1.1 โ†’ 1.1.2) - ---- - -## Publishing Steps - -### Step 1: Final Preparation - -```bash -# 1. Ensure you're on the main branch and it's up to date -git checkout main -git pull origin main - -# 2. Clean install dependencies -rm -rf node_modules package-lock.json -npm install - -# 3. Run full test suite -npm test -npm run test:perf -npm run test:migration - -# 4. Clean build -rm -rf dist -npm run build - -# 5. Verify package contents -npm pack --dry-run -``` - -### Step 2: Version Bump (if needed) - -If you need to bump the version before publishing: - -```bash -# For patch release (bug fixes): 1.1.1 โ†’ 1.1.2 -npm run version:patch - -# For minor release (new features): 1.1.1 โ†’ 1.2.0 -npm run version:minor - -# For major release (breaking changes): 1.1.1 โ†’ 2.0.0 -npm run version:major - -# This automatically updates: -# - package.json version -# - Creates git tag -# - Updates CHANGELOG.md (if applicable) -``` - -**Note:** Our automated version bump workflow handles this on commits to main, so manual version bumps are typically only needed for manual releases. - -### Step 3: Publish to NPM - -```bash -# Standard publish (public package) -npm publish - -# With 2FA (append one-time password) -npm publish --otp=123456 - -# First-time publish should succeed if name is available -``` - -**Expected output:** -``` -+ simple-memory-mcp@1.1.1 -``` - -### Step 4: Verify Publication - -```bash -# Check package page -npm view simple-memory-mcp - -# Should show: -# - Version number -# - Description -# - Dependencies -# - Dist-tags -# - etc. - -# Visit package page -# https://www.npmjs.com/package/simple-memory-mcp -``` - -### Step 5: Test Installation - -**Test in a fresh environment:** - -```bash -# Create test directory -mkdir /tmp/test-npm-install -cd /tmp/test-npm-install - -# Global installation test -npm install -g simple-memory-mcp - -# Verify command is available -simple-memory --version -simple-memory stats - -# Test basic functionality -simple-memory store --content "Test memory" --tags "test" -simple-memory search --query "Test" - -# Cleanup -npm uninstall -g simple-memory-mcp -cd - -rm -rf /tmp/test-npm-install -``` - ---- - -## Post-Publication Tasks - -### 1. Create Git Tag and Release - -```bash -# Tag the release (if not already done by version bump) -git tag -a v1.1.1 -m "Release version 1.1.1" -git push origin v1.1.1 - -# Create GitHub Release -# Go to: https://github.com/chrisribe/simple-memory-mcp/releases/new -# - Select tag: v1.1.1 -# - Title: "v1.1.1 - [Brief description]" -# - Description: Copy from CHANGELOG.md -# - Attach binaries if applicable -# - Click "Publish release" -``` - -### 2. Update Documentation - -- [ ] Update README.md installation instructions (if changed) -- [ ] Add release notes to CHANGELOG.md -- [ ] Update any version references in documentation -- [ ] Verify npm badges show correct version - -### 3. Announce the Release - -Consider announcing on: -- [ ] GitHub Discussions -- [ ] Project Discord/Slack (if applicable) -- [ ] Twitter/Social media -- [ ] Dev.to or Medium (if you blog) - -**Sample announcement:** -``` -๐ŸŽ‰ simple-memory-mcp v1.1.1 is now available on NPM! - -A blazingly fast MCP server for persistent memory storage with intelligent -tagging and full-text search. - -Install: npm install -g simple-memory-mcp - -Features: -- Sub-millisecond performance -- Full-text search with SQLite FTS5 -- Smart tagging and auto-relationships -- Zero-config setup - -https://www.npmjs.com/package/simple-memory-mcp -https://github.com/chrisribe/simple-memory-mcp -``` - -### 4. Monitor Initial Usage - -**First 24-48 hours:** -- [ ] Check npm download stats: https://npm-stat.com/charts.html?package=simple-memory-mcp -- [ ] Monitor GitHub issues for installation problems -- [ ] Watch for community feedback - ---- - -## Updating Published Package - -### For Patch/Minor Updates - -```bash -# 1. Make your changes -# 2. Test thoroughly -npm test - -# 3. Build -npm run build - -# 4. Bump version -npm run version:patch # or version:minor - -# 5. Publish -npm publish --otp=123456 # if using 2FA -``` - -### For Major Updates (Breaking Changes) - -**Extra care required:** - -1. **Update CHANGELOG.md** with clear migration guide -2. **Document breaking changes** in README.md -3. **Consider deprecation warnings** before removing features -4. **Test extensively** with real-world use cases -5. **Bump to next major version:** `npm run version:major` -6. **Publish with release notes** - -### Deprecating Old Versions - -If you need to deprecate an old version: - -```bash -# Deprecate a specific version -npm deprecate simple-memory-mcp@1.0.0 "Please upgrade to v1.1.0 or higher" - -# Deprecate all versions below a certain version -npm deprecate simple-memory-mcp@"<1.1.0" "Version 1.1.0+ required for security fixes" -``` - ---- - -## Troubleshooting - -### Common Issues - -#### 1. "You do not have permission to publish" - -**Solution:** -```bash -# Verify you're logged in -npm whoami - -# If not logged in: -npm login - -# Check package.json name doesn't conflict -npm view simple-memory-mcp -``` - -#### 2. "Package name too similar to existing package" - -**Solution:** -- If legitimate conflict, consider scoped package: `@chrisribe/simple-memory-mcp` -- Update package.json: `"name": "@chrisribe/simple-memory-mcp"` -- Publish scoped package: `npm publish --access=public` - -#### 3. "Version already exists" - -**Solution:** -```bash -# Check current published version -npm view simple-memory-mcp version - -# Bump to next version -npm run version:patch -npm publish -``` - -#### 4. "npm ERR! 403 Forbidden" - -**Possible causes:** -- 2FA required but not provided: Use `--otp=123456` -- Not logged in: Run `npm login` -- No permission for scoped package: Use `--access=public` -- Package name taken: Change package name - -#### 5. "prepublishOnly script failed" - -**Solution:** -```bash -# Our prepublishOnly runs build -# If it fails, check build errors: -npm run build - -# Fix TypeScript errors, then retry -npm publish -``` - -### Testing Package Locally Before Publishing - -**Use `npm link` for local testing:** - -```bash -# In package directory -npm link - -# In another project -npm link simple-memory-mcp - -# Test functionality -# ... - -# Unlink when done -npm unlink simple-memory-mcp # in test project -npm unlink -g # in package directory -``` - -**Or use tarball:** - -```bash -# Create tarball -npm pack - -# Install in test project -cd /path/to/test/project -npm install /path/to/simple-memory-mcp-1.1.1.tgz - -# Test, then cleanup -npm uninstall simple-memory-mcp -``` - ---- - -## Security Best Practices - -### 1. Enable 2FA - -**Mandatory for popular packages:** -- Go to npm settings -- Enable 2FA for "Authorization and Publishing" -- Keep backup codes safe - -### 2. Audit Dependencies Regularly - -```bash -# Check for vulnerabilities -npm audit - -# Fix automatically -npm audit fix - -# Check before every publish -``` - -### 3. Review Package Contents - -**Before publishing, always check:** -```bash -npm pack --dry-run - -# Ensure no sensitive data: -# - No .env files -# - No private keys -# - No database files -# - No credentials -``` - -### 4. Use .npmignore or "files" in package.json - -We use the `"files"` array in package.json for explicit control: -```json -{ - "files": [ - "dist/**/*", - "README.md", - "LICENSE" - ] -} -``` - -This is safer than `.npmignore` (whitelist vs blacklist). - -### 5. Avoid Typosquatting - -- Use exact package name in documentation -- Monitor for similar package names -- Report suspicious packages to npm - ---- - -## Additional Resources - -- **NPM Documentation:** https://docs.npmjs.com/ -- **Semantic Versioning:** https://semver.org/ -- **Package.json Guide:** https://docs.npmjs.com/cli/v10/configuring-npm/package-json -- **Publishing Packages:** https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry -- **Package Security:** https://docs.npmjs.com/packages-and-modules/securing-your-code - ---- - -## Quick Reference - -```bash -# Login -npm login - -# Verify login -npm whoami - -# Check package availability -npm view simple-memory-mcp - -# Dry run package contents -npm pack --dry-run - -# Bump version -npm run version:patch - -# Publish -npm publish - -# Publish with 2FA -npm publish --otp=123456 - -# Check published package -npm view simple-memory-mcp - -# Test install -npm install -g simple-memory-mcp -``` - ---- - -**Ready to publish? ๐Ÿš€** - -Follow the [PUBLISHING_CHECKLIST.md](./PUBLISHING_CHECKLIST.md) to ensure you haven't missed anything! diff --git a/docs/NPM_PUBLISHING_SUMMARY.md b/docs/NPM_PUBLISHING_SUMMARY.md deleted file mode 100644 index a5a5493..0000000 --- a/docs/NPM_PUBLISHING_SUMMARY.md +++ /dev/null @@ -1,514 +0,0 @@ -# NPM Publishing Readiness Summary - -**Status: โœ… READY TO PUBLISH** - -This document summarizes the assessment of `simple-memory-mcp` for NPM publication. - ---- - -## Executive Summary - -The `simple-memory-mcp` package is **ready for publication to NPM**. All critical requirements are met, documentation is comprehensive, and quality checks pass. - -**Package was previously published and unpublished on 2025-06-21. The name is now available for re-publishing.** - -### Key Findings - -โœ… **All tests pass** (11/11 GraphQL tests, performance tests, migration tests) -โœ… **No security vulnerabilities** (npm audit clean) -โœ… **LICENSE file created** (MIT) -โœ… **Documentation complete** (README, guides, checklists) -โœ… **Package metadata correct** (name, version, keywords, etc.) -โœ… **Build process works** (TypeScript โ†’ JavaScript compilation) -โœ… **Package size reasonable** (96.7 KB packed, 438.2 KB unpacked) - ---- - -## What Was Done - -### 1. Critical Fixes - -**Added LICENSE File:** -- Created MIT LICENSE file (was referenced in package.json but missing) -- Now included in npm package distribution - -**Fixed Security Vulnerabilities:** -```bash -Before: 2 vulnerabilities (1 moderate, 1 high) -After: 0 vulnerabilities โœ“ -``` - -Updated dependencies: -- `@modelcontextprotocol/sdk` to v1.24.0+ (fixed DNS rebinding vulnerability) -- `body-parser` (fixed denial of service vulnerability) - -### 2. Documentation Created - -**Comprehensive Publishing Guides:** - -1. **[NPM_PUBLISHING_GUIDE.md](./NPM_PUBLISHING_GUIDE.md)** (11KB) - - Complete step-by-step publishing process - - Prerequisites (NPM account, 2FA setup) - - Pre-publication checklist - - Publishing steps with examples - - Post-publication tasks - - Troubleshooting common issues - - Security best practices - -2. **[PUBLISHING_CHECKLIST.md](./PUBLISHING_CHECKLIST.md)** (9.5KB) - - Detailed verification checklist - - Pre-flight checks (critical items) - - Functional testing procedures - - Cross-platform testing - - Red flags to watch for - - Pre-publish verification script - -3. **[MAINTENANCE_GUIDE.md](./MAINTENANCE_GUIDE.md)** (18.5KB) - - Regular maintenance tasks (weekly, monthly, quarterly, yearly) - - Dependency management strategies - - Version management and semver - - Security maintenance procedures - - Community management - - Things beginners often miss - - Long-term considerations - -4. **[NPM_QUICK_START.md](./NPM_QUICK_START.md)** (1.9KB) - - Quick reference for experienced developers - - One-page TL;DR version - - Common commands - - Troubleshooting quick fixes - -### 3. Package Verification - -**Package Contents Verified:** -``` -โœ“ dist/**/* (compiled JavaScript + source maps) -โœ“ README.md (comprehensive documentation) -โœ“ LICENSE (MIT license) -โœ“ package.json (metadata) - -Total: 139 files, 96.7 KB packed -``` - -**What's Excluded (Correct):** -``` -โœ“ src/ (TypeScript source - not needed in published package) -โœ“ node_modules/ (dependencies installed by users) -โœ“ .env files (environment variables) -โœ“ *.db* files (database files) -โœ“ tests/ (included but that's OK for now) -``` - -**Note:** Test files are currently included in the package (1.4KB). This is acceptable but could be excluded in a future optimization by updating the `"files"` array in package.json. - ---- - -## Current Package Status - -### Package Metadata (package.json) - -```json -{ - "name": "simple-memory-mcp", โœ“ Available on NPM - "version": "1.1.1", โœ“ Valid semver - "description": "...", โœ“ Clear and concise - "main": "dist/index.js", โœ“ Correct entry point - "type": "module", โœ“ ES modules - "bin": { "simple-memory": "..." }, โœ“ CLI command - "license": "MIT", โœ“ LICENSE file exists - "keywords": [...], โœ“ Good for SEO - "repository": "...", โœ“ Correct URL - "author": "chrisribe", โœ“ Set - "files": [...], โœ“ Controlled distribution - "scripts": { "prepublishOnly": "..." } โœ“ Auto-build before publish -} -``` - -### Quality Metrics - -| Metric | Status | Details | -|--------|--------|---------| -| **Tests** | โœ… Passing | 11/11 GraphQL tests pass in 45ms | -| **Performance** | โœ… Excellent | Sub-millisecond operations | -| **Security** | โœ… Clean | 0 vulnerabilities | -| **Build** | โœ… Works | TypeScript compiles without errors | -| **Documentation** | โœ… Complete | README + 4 publishing guides | -| **License** | โœ… Present | MIT license file | -| **Size** | โœ… Reasonable | < 100KB packed | -| **Dependencies** | โœ… Updated | All dependencies current | - -### NPM Readiness Checklist - -**Critical Requirements:** -- [x] Package name available -- [x] Valid semantic version -- [x] LICENSE file exists -- [x] README.md complete -- [x] Tests pass -- [x] Build succeeds -- [x] No security vulnerabilities -- [x] Package contents verified - -**Recommended:** -- [x] 2FA guide provided -- [x] Version management documented -- [x] Maintenance guide provided -- [x] Troubleshooting documented -- [x] Git repository clean - -**Optional (for future):** -- [ ] CONTRIBUTING.md (nice to have for community) -- [ ] CODE_OF_CONDUCT.md (nice to have if project grows) -- [ ] Automated publishing via GitHub Actions (optional) - ---- - -## Publishing Steps - -**The package is ready! Here's what to do next:** - -### Option 1: Manual Publish (Recommended for First-Time) - -Follow the [NPM_PUBLISHING_GUIDE.md](./NPM_PUBLISHING_GUIDE.md): - -```bash -# 1. Login to NPM -npm login - -# 2. Run pre-publish checks -npm audit # Should show 0 vulnerabilities โœ“ -npm run build # Should succeed โœ“ -npm test # Should pass 11/11 tests โœ“ -npm pack --dry-run # Verify contents โœ“ - -# 3. Publish -npm publish # Add --otp=123456 if using 2FA - -# 4. Verify -npm view simple-memory-mcp -npm install -g simple-memory-mcp -simple-memory --version - -# 5. Create GitHub release -git tag -a v1.1.1 -m "Release v1.1.1" -git push origin v1.1.1 -``` - -### Option 2: Use Automated Checklist - -Run the pre-publish verification script from [PUBLISHING_CHECKLIST.md](./PUBLISHING_CHECKLIST.md): - -```bash -# Save the script from the checklist doc as pre-publish-check.sh -chmod +x pre-publish-check.sh -./pre-publish-check.sh && npm publish -``` - ---- - -## Things to Know - -### Package Name History - -- **Previous status:** Published then unpublished on 2025-06-21 -- **Current status:** Name is available for publishing -- **Implication:** This is like a fresh start, no version conflicts - -### Version Strategy - -**Current version: 1.1.1** -- Already at a mature version number (> 1.0.0) -- Indicates stable, production-ready software -- Breaking changes would require bumping to 2.0.0 -- Use automated version bump scripts: - - `npm run version:patch` โ†’ 1.1.2 (bug fixes) - - `npm run version:minor` โ†’ 1.2.0 (new features) - - `npm run version:major` โ†’ 2.0.0 (breaking changes) - -### Automated Workflows - -**Already in place:** -- GitHub Actions auto-version bump on commits to main -- Skips version bumps for docs-only changes -- Automatic build before publish (`prepublishOnly` script) - ---- - -## Common Beginner Mistakes to Avoid - -### โŒ Don't Do These: - -1. **Publishing without testing install** - ```bash - # Wrong: Just publish - npm publish - - # Right: Test first - npm pack - npm install -g ./simple-memory-mcp-1.1.1.tgz - simple-memory --version - npm uninstall -g simple-memory-mcp - npm publish - ``` - -2. **Forgetting to bump version** - ```bash - # Wrong: Publish same version twice (will fail) - npm publish - - # Right: Bump version first - npm run version:patch - npm publish - ``` - -3. **Not reading npm audit warnings** - ```bash - # Always run before publishing: - npm audit - # Fix any issues before publishing - ``` - -4. **Publishing with dirty git state** - ```bash - # Check first: - git status # Should be clean - ``` - -5. **Not testing the CLI command** - ```bash - # After global install, verify: - simple-memory --version # Should work - simple-memory stats # Should work - ``` - -6. **Ignoring 2FA warnings** - - If NPM shows 2FA warnings, set it up - - It protects your package from hijacking - - See guide: [NPM_PUBLISHING_GUIDE.md](./NPM_PUBLISHING_GUIDE.md#2-two-factor-authentication-2fa) - -7. **Not creating git tags** - ```bash - # After publishing, always tag: - git tag -a v1.1.1 -m "Release v1.1.1" - git push origin v1.1.1 - ``` - -8. **Publishing without updating CHANGELOG** - - Update CHANGELOG.md before publishing - - Move items from "Unreleased" to new version section - - Users need to know what changed - ---- - -## What Happens After Publishing - -### Immediate (< 1 hour) - -1. **Package appears on NPM** - - https://www.npmjs.com/package/simple-memory-mcp - - README renders on package page - - Version shows as latest - -2. **Installable globally** - ```bash - npm install -g simple-memory-mcp - ``` - -3. **Badges update** (if in README) - - Version badge shows 1.1.1 - - License badge shows MIT - -### First 24-48 Hours - -1. **Monitor for issues** - - GitHub issues (installation problems?) - - NPM downloads (are people using it?) - - Community feedback - -2. **Download stats become available** - - https://npm-stat.com/charts.html?package=simple-memory-mcp - - Track adoption over time - -### Ongoing - -1. **Maintenance** (see [MAINTENANCE_GUIDE.md](./MAINTENANCE_GUIDE.md)) - - Weekly: Monitor issues, security checks - - Monthly: Dependency updates - - Quarterly: Major updates, compatibility testing - - Yearly: Review lifecycle, deprecation decisions - -2. **Community engagement** - - Respond to issues - - Review pull requests - - Help users with questions - - Build community around package - ---- - -## Quick Reference - -### Documents Created - -| Document | Purpose | Size | Audience | -|----------|---------|------|----------| -| [NPM_PUBLISHING_GUIDE.md](./NPM_PUBLISHING_GUIDE.md) | Complete publishing process | 11KB | First-time publishers | -| [PUBLISHING_CHECKLIST.md](./PUBLISHING_CHECKLIST.md) | Pre-publish verification | 9.5KB | Everyone before publish | -| [MAINTENANCE_GUIDE.md](./MAINTENANCE_GUIDE.md) | Ongoing maintenance | 18.5KB | Package maintainers | -| [NPM_QUICK_START.md](./NPM_QUICK_START.md) | Quick reference | 1.9KB | Experienced developers | -| **This document** | Overall summary | 8KB | Decision makers | - -### Essential Commands - -```bash -# Pre-publish -npm audit # Security check -npm run build # Build check -npm test # Functionality check -npm pack --dry-run # Content check - -# Publish -npm login # One-time login -npm publish # Publish package -npm publish --otp=123456 # With 2FA - -# Post-publish -git tag -a v1.1.1 -m "Release" # Tag release -git push --follow-tags # Push tag -npm view simple-memory-mcp # Verify published - -# Testing -npm install -g simple-memory-mcp # Install globally -simple-memory --version # Test command -npm uninstall -g simple-memory-mcp # Clean up -``` - ---- - -## Risks & Mitigation - -### Identified Risks - -| Risk | Severity | Mitigation | Status | -|------|----------|------------|--------| -| Security vulnerabilities | High | Run `npm audit` before publish | โœ… Clean | -| Missing LICENSE | High | Created MIT LICENSE file | โœ… Fixed | -| Version conflicts | Medium | Check `npm view simple-memory-mcp` | โœ… Name available | -| Large package size | Low | Verify with `npm pack --dry-run` | โœ… Only 96.7KB | -| Platform compatibility | Low | Test on Windows/Mac/Linux | โš ๏ธ Manual test needed | -| Broken installation | Medium | Test global install before publish | โš ๏ธ Manual test needed | - -### Remaining Manual Tests - -Before first publish, manually test: - -1. **Global installation:** - ```bash - npm pack - npm install -g ./simple-memory-mcp-1.1.1.tgz - simple-memory --version - simple-memory stats - ``` - -2. **Platform-specific** (if possible): - - Windows: Test CLI execution - - macOS: Test CLI execution - - Linux: Test CLI execution (already tested in CI) - -3. **MCP integration:** - - Test with VS Code MCP client - - Test with Claude Desktop (if available) - ---- - -## Recommendations - -### Before First Publish - -1. โœ… **Read the publishing guide** - [NPM_PUBLISHING_GUIDE.md](./NPM_PUBLISHING_GUIDE.md) -2. โœ… **Run the checklist** - [PUBLISHING_CHECKLIST.md](./PUBLISHING_CHECKLIST.md) -3. โš ๏ธ **Test global install manually** (see above) -4. โš ๏ธ **Set up 2FA on NPM account** (security) -5. โœ… **Review package contents** - `npm pack --dry-run` - -### After First Publish - -1. **Monitor closely** for first 48 hours -2. **Respond quickly** to any installation issues -3. **Update README** with npm badges if desired -4. **Announce** on relevant channels (Twitter, Reddit, etc.) - -### Long-Term - -1. **Follow maintenance guide** - [MAINTENANCE_GUIDE.md](./MAINTENANCE_GUIDE.md) -2. **Keep dependencies updated** - Monthly `npm update` -3. **Respond to community** - Issues, PRs, questions -4. **Stay informed** - Watch for MCP SDK updates - ---- - -## Next Steps - -**Ready to publish? Here's your path:** - -1. **Review this summary** โœ“ (you're here) - -2. **Read the full guide** - - [NPM_PUBLISHING_GUIDE.md](./NPM_PUBLISHING_GUIDE.md) - -3. **Run the checklist** - - [PUBLISHING_CHECKLIST.md](./PUBLISHING_CHECKLIST.md) - -4. **Publish!** - ```bash - npm login - npm publish - ``` - -5. **Post-publish tasks** - - Create git tag - - GitHub release - - Announce to community - -6. **Ongoing maintenance** - - Follow [MAINTENANCE_GUIDE.md](./MAINTENANCE_GUIDE.md) - ---- - -## Questions? - -**For publishing questions:** -- See [NPM_PUBLISHING_GUIDE.md](./NPM_PUBLISHING_GUIDE.md) โ†’ Troubleshooting section -- NPM documentation: https://docs.npmjs.com/ - -**For maintenance questions:** -- See [MAINTENANCE_GUIDE.md](./MAINTENANCE_GUIDE.md) -- GitHub issues: https://github.com/chrisribe/simple-memory-mcp/issues - -**For package questions:** -- See [README.md](../README.md) -- Design philosophy: [DESIGN_PHILOSOPHY.md](./DESIGN_PHILOSOPHY.md) - ---- - -## Conclusion - -**The `simple-memory-mcp` package is production-ready and prepared for NPM publication.** - -All critical requirements are met: -- โœ… Code quality (tests pass, builds successfully) -- โœ… Security (no vulnerabilities, LICENSE file) -- โœ… Documentation (comprehensive guides created) -- โœ… Metadata (package.json complete) -- โœ… Best practices (version management, dependencies) - -**Confidence level: HIGH** - -The package has been thoroughly reviewed, tested, and documented. The comprehensive guides will help avoid common pitfalls and ensure long-term success. - -**Recommendation: Proceed with publishing when ready! ๐Ÿš€** - ---- - -*Document created: 2025-12-04* -*Last updated: 2025-12-04* -*Package version: 1.1.1* diff --git a/docs/NPM_QUICK_START.md b/docs/NPM_QUICK_START.md deleted file mode 100644 index 118658a..0000000 --- a/docs/NPM_QUICK_START.md +++ /dev/null @@ -1,118 +0,0 @@ -# NPM Publishing Quick Start - -**TL;DR version of the publishing guide for experienced developers.** - -## Prerequisites โœ“ - -```bash -npm login -npm whoami # Verify -``` - -## Pre-Publish Checklist โœ“ - -```bash -# 1. Clean & Install -rm -rf node_modules package-lock.json && npm install - -# 2. Security -npm audit # Must show 0 vulnerabilities - -# 3. Build -rm -rf dist && npm run build - -# 4. Test -npm test && npm run test:perf && npm run test:migration - -# 5. Verify package -npm pack --dry-run - -# 6. Version check -cat package.json | grep version -``` - -## Publish ๐Ÿš€ - -```bash -# Standard -npm publish - -# With 2FA -npm publish --otp=123456 -``` - -## Post-Publish โœ“ - -```bash -# 1. Git tag -git tag -a v1.1.1 -m "Release v1.1.1" -git push origin v1.1.1 - -# 2. Verify -npm view simple-memory-mcp -npm install -g simple-memory-mcp -simple-memory --version - -# 3. GitHub Release -# https://github.com/chrisribe/simple-memory-mcp/releases/new -``` - -## Update Package ๐Ÿ”„ - -```bash -# 1. Make changes & test -npm test - -# 2. Bump version -npm run version:patch # or minor, major - -# 3. Publish -npm publish --otp=123456 - -# 4. Tag & push -git push --follow-tags -``` - ---- - -## Common Issues ๐Ÿ”ง - -**"Permission denied"** -```bash -npm login -``` - -**"Version already exists"** -```bash -npm run version:patch -``` - -**"Vulnerabilities found"** -```bash -npm audit fix -npm test # Verify still works -``` - -**"Package too large"** -```bash -npm pack --dry-run # Check what's included -# Verify "files" array in package.json -``` - ---- - -## Full Documentation - -- ๐Ÿ“˜ [Complete Publishing Guide](./NPM_PUBLISHING_GUIDE.md) -- โœ… [Detailed Checklist](./PUBLISHING_CHECKLIST.md) -- ๐Ÿ› ๏ธ [Maintenance Guide](./MAINTENANCE_GUIDE.md) - ---- - -## One-Liner Publish (For Advanced Users) - -```bash -git status && npm audit && npm run build && npm test && npm pack --dry-run && npm publish --otp=$(read -p "OTP: " otp && echo $otp) && git push --follow-tags -``` - -**Use with caution!** This skips verification steps. diff --git a/docs/PUBLISHING_CHECKLIST.md b/docs/PUBLISHING_CHECKLIST.md deleted file mode 100644 index 0abbc28..0000000 --- a/docs/PUBLISHING_CHECKLIST.md +++ /dev/null @@ -1,350 +0,0 @@ -# NPM Publishing Checklist - -Use this checklist before publishing to NPM to ensure quality and avoid common mistakes. - -## ๐ŸŽฏ Pre-Flight Checks (Critical) - -### Package Identity -- [ ] Package name is correct and available: `simple-memory-mcp` -- [ ] Version follows semver (MAJOR.MINOR.PATCH format) -- [ ] Version is higher than the last published version -- [ ] Description is clear, concise, and accurate (< 150 chars ideal) - -### Legal & Licensing -- [ ] LICENSE file exists and is correct (MIT) -- [ ] LICENSE is referenced in package.json -- [ ] No copyright violations in code or documentation -- [ ] Third-party licenses are properly attributed (if applicable) - -### Code Quality -- [ ] All TypeScript compiles without errors: `npm run build` -- [ ] All tests pass: `npm test` -- [ ] Performance tests pass: `npm run test:perf` -- [ ] Migration tests pass: `npm run test:migration` -- [ ] No ESLint/TSLint errors (if applicable) -- [ ] Code is properly formatted - -### Security -- [ ] No security vulnerabilities: `npm audit` shows 0 vulnerabilities -- [ ] Dependencies are up to date -- [ ] No secrets/credentials in code or config files -- [ ] No .env files included in package -- [ ] Sensitive data properly excluded via "files" array - -### Package Contents -- [ ] Verified package contents: `npm pack --dry-run` -- [ ] Only necessary files included (dist/, README.md, LICENSE) -- [ ] Source files (src/) excluded -- [ ] Test files excluded -- [ ] Database files (*.db*) excluded -- [ ] node_modules excluded -- [ ] Development config files excluded -- [ ] Total package size is reasonable (< 5MB unpacked ideal) - -### Documentation -- [ ] README.md is comprehensive and up to date -- [ ] Installation instructions are clear -- [ ] Usage examples work as documented -- [ ] API documentation is accurate -- [ ] CHANGELOG.md updated with latest changes -- [ ] All code examples have been tested -- [ ] Links in README work (no 404s) - -### package.json Metadata -- [ ] `"name"` is correct -- [ ] `"version"` is correct -- [ ] `"description"` is accurate and helpful -- [ ] `"keywords"` are relevant for discoverability (check we have: mcp, model-context-protocol, memory, storage, sqlite, tags, ai, llm) -- [ ] `"author"` is set correctly -- [ ] `"license"` is "MIT" -- [ ] `"main"` points to `dist/index.js` -- [ ] `"type": "module"` is set (for ES modules) -- [ ] `"bin"` is configured for CLI: `simple-memory` -- [ ] `"files"` array correctly lists what to include -- [ ] `"repository"` URL is correct -- [ ] `"bugs"` URL is correct -- [ ] `"homepage"` URL is correct - -### Scripts -- [ ] `"prepublishOnly"` runs build: `npm run build` -- [ ] `"postbuild"` makes CLI executable (Unix) -- [ ] All npm scripts work as expected -- [ ] No broken script references - -### Dependencies -- [ ] All dependencies are necessary (no unused packages) -- [ ] Versions are pinned or use reasonable ranges -- [ ] Dev dependencies are in `devDependencies`, not `dependencies` -- [ ] Peer dependencies documented (if applicable) -- [ ] Native dependencies work on target platforms - ---- - -## ๐Ÿš€ Functional Testing - -### Installation Tests -- [ ] Global install works: `npm install -g ./` (from package directory) -- [ ] CLI command available: `simple-memory --version` -- [ ] CLI command works: `simple-memory stats` -- [ ] Uninstall works: `npm uninstall -g simple-memory-mcp` - -### Feature Tests -- [ ] MCP server starts without errors -- [ ] Store memory works: `simple-memory store --content "test"` -- [ ] Search works: `simple-memory search --query "test"` -- [ ] GraphQL queries work: `simple-memory graphql --query "{ stats { totalMemories } }"` -- [ ] Export/import works -- [ ] All shortcut commands work -- [ ] Help displays correctly: `simple-memory --help` -- [ ] Version displays correctly: `simple-memory --version` - -### Cross-Platform Tests -- [ ] Tested on Linux (if applicable) -- [ ] Tested on macOS (if applicable) -- [ ] Tested on Windows (if applicable) -- [ ] Shebang in dist/index.js is correct: `#!/usr/bin/env node` -- [ ] File permissions are correct (executable flag on Unix) - -### Integration Tests -- [ ] Works with VS Code MCP client -- [ ] Works with Claude Desktop (if applicable) -- [ ] Works as MCP server (stdio transport) -- [ ] Works as HTTP server (if applicable) -- [ ] Database migrations work correctly - ---- - -## ๐Ÿ“Š Publishing Environment - -### NPM Account -- [ ] Logged in to NPM: `npm whoami` -- [ ] Account has publish permissions -- [ ] 2FA is enabled on NPM account (recommended) -- [ ] Have access to 2FA codes/app if required - -### Git Repository -- [ ] All changes committed -- [ ] Working directory is clean: `git status` -- [ ] On correct branch (main) -- [ ] Branch is up to date: `git pull origin main` -- [ ] No merge conflicts - -### Version Control -- [ ] Git tag will be created for this version -- [ ] GitHub release notes prepared -- [ ] CHANGELOG.md reflects this version - ---- - -## ๐ŸŽจ Optional Quality Checks - -### Documentation Polish -- [ ] Badges in README are up to date -- [ ] Screenshots/GIFs are current (if applicable) -- [ ] Contributing guidelines exist (optional) -- [ ] Code of conduct exists (optional for larger projects) -- [ ] Acknowledgments/credits are complete - -### SEO & Discoverability -- [ ] Package name is searchable and memorable -- [ ] Keywords cover main use cases -- [ ] Description contains main keywords -- [ ] README has clear value proposition in first paragraph -- [ ] Examples are practical and relatable - -### Community -- [ ] GitHub issues template (optional) -- [ ] Pull request template (optional) -- [ ] Discussion board enabled (optional) - ---- - -## โšก Pre-Publish Commands - -Run these in sequence before `npm publish`: - -```bash -# 1. Clean state -git status # Should be clean -npm whoami # Should show your username - -# 2. Clean install -rm -rf node_modules package-lock.json -npm install - -# 3. Security check -npm audit # Should show 0 vulnerabilities - -# 4. Build -rm -rf dist -npm run build # Should succeed - -# 5. Test everything -npm test # All tests pass -npm run test:perf # Performance tests pass -npm run test:migration # Migration tests pass - -# 6. Verify package contents -npm pack --dry-run # Review file list - -# 7. Version check -npm version # Verify version number - -# 8. Test install locally -npm install -g ./ -simple-memory --version -simple-memory stats -npm uninstall -g simple-memory-mcp -``` - ---- - -## ๐Ÿ“ฆ Publishing Commands - -```bash -# Standard publish -npm publish - -# With 2FA -npm publish --otp=123456 - -# First-time publish of scoped package -npm publish --access=public - -# Dry run (test without publishing) -npm publish --dry-run -``` - ---- - -## โœ… Post-Publish Verification - -### Immediate Checks -- [ ] Package appears on NPM: https://www.npmjs.com/package/simple-memory-mcp -- [ ] Correct version is shown -- [ ] README renders correctly on NPM -- [ ] Install works: `npm install -g simple-memory-mcp` -- [ ] Downloaded package works as expected - -### Git Tasks -- [ ] Create and push git tag: `git tag -a v1.1.1 -m "Release v1.1.1"` -- [ ] Push tag: `git push origin v1.1.1` -- [ ] Create GitHub Release with changelog - -### Monitoring -- [ ] Watch for issues in first 24 hours -- [ ] Monitor download stats -- [ ] Check for community feedback - ---- - -## ๐Ÿšจ Red Flags - Stop Publishing If: - -- โŒ Any tests fail -- โŒ npm audit shows vulnerabilities -- โŒ Build fails or has errors -- โŒ Package size > 10MB (investigate why) -- โŒ Wrong version number -- โŒ Missing LICENSE file -- โŒ Secrets/credentials in code -- โŒ Not logged in to npm -- โŒ Git working directory is dirty -- โŒ README has broken links or examples -- โŒ CLI doesn't work when installed globally - ---- - -## ๐Ÿ“ Checklist Summary - -**Before you run `npm publish`, you should have checked off:** - -**Critical (Must Have):** -- All code quality checks pass โœ“ -- All security checks pass โœ“ -- Package contents verified โœ“ -- Documentation complete โœ“ -- Functional tests pass โœ“ - -**Recommended (Should Have):** -- Cross-platform testing โœ“ -- Git repository clean โœ“ -- Version control ready โœ“ - -**Optional (Nice to Have):** -- Community documentation โœ“ -- SEO optimization โœ“ - ---- - -## ๐ŸŽฏ Quick Pre-Publish Script - -Save this as a script to run before publishing: - -```bash -#!/bin/bash -# pre-publish-check.sh - -echo "๐Ÿ” Running pre-publish checks..." - -# Clean state -if [[ -n $(git status -s) ]]; then - echo "โŒ Git working directory is not clean" - exit 1 -fi - -# Dependencies -echo "๐Ÿ“ฆ Installing dependencies..." -rm -rf node_modules package-lock.json -npm install - -# Security -echo "๐Ÿ”’ Checking security..." -if npm audit | grep -q "vulnerabilities"; then - echo "โŒ Security vulnerabilities found" - npm audit - exit 1 -fi - -# Build -echo "๐Ÿ”จ Building..." -rm -rf dist -npm run build || exit 1 - -# Tests -echo "๐Ÿงช Running tests..." -npm test || exit 1 -npm run test:perf || exit 1 -npm run test:migration || exit 1 - -# Package contents -echo "๐Ÿ“‹ Checking package contents..." -npm pack --dry-run - -echo "" -echo "โœ… All pre-publish checks passed!" -echo "๐Ÿ“ฆ Ready to publish with: npm publish" -echo "" -echo "Version: $(node -p "require('./package.json').version")" -echo "Files: $(npm pack --dry-run 2>&1 | grep 'total files' | awk '{print $3}')" -``` - -Make it executable: -```bash -chmod +x pre-publish-check.sh -``` - -Run before publishing: -```bash -./pre-publish-check.sh && npm publish -``` - ---- - -**๐ŸŽ‰ Ready to Publish?** - -If all checks pass, proceed with confidence: -```bash -npm publish --otp=123456 # if using 2FA -``` - -Good luck! ๐Ÿš€