pms_md 1.0.0

package/node-monitor/PUBLISHING_GUIDE.md

@@ -0,0 +1,331 @@
+# 📦 Publishing Guide for Node Monitor
+
+This guide will help you publish the `@projectmd/node-monitor` package to npm.
+
+## 🎯 Pre-Publishing Checklist
+
+Before publishing, make sure:
+
+- [x] ✅ `.npmignore` file is created
+- [x] ✅ `package.json` has repository information
+- [x] ✅ `LICENSE` file exists (MIT)
+- [x] ✅ `README.md` is complete
+- [ ] 📝 All documentation is up to date
+- [ ] 🧪 All tests pass (if applicable)
+- [ ] 🔍 No sensitive data in code (API keys, passwords)
+- [ ] 📊 Version number is correct
+
+---
+
+## 🚀 Step-by-Step Publishing Process
+
+### Step 1: Create npm Account (If You Don't Have One)
+
+1. Go to: https://www.npmjs.com/signup
+2. Create an account
+3. Verify your email
+
+### Step 2: Login to npm
+
+```bash
+# Login to npm
+npm login
+
+# Verify you're logged in
+npm whoami
+```
+
+You'll be prompted for:
+- Username
+- Password
+- Email
+- One-time password (if 2FA is enabled)
+
+### Step 3: Test Your Package Locally
+
+```bash
+# Navigate to the package directory
+cd node-monitor
+
+# Create a test package (doesn't publish, just creates a .tgz file)
+npm pack
+
+# This creates: projectmd-node-monitor-1.0.0.tgz
+```
+
+**Test the package in another project:**
+
+```bash
+# In a test project
+cd ../test-project
+npm install ../node-monitor/projectmd-node-monitor-1.0.0.tgz
+
+# Test if it works
+node -e "const monitor = require('@projectmd/node-monitor'); console.log('✅ Package works!');"
+```
+
+### Step 4: Dry Run (See What Will Be Published)
+
+```bash
+cd node-monitor
+
+# Dry run - shows what will be published without actually publishing
+npm publish --dry-run --access public
+```
+
+This will show:
+- Files that will be included
+- Package size
+- Any warnings or errors
+
+### Step 5: Publish to npm
+
+```bash
+# Publish the package
+npm publish --access public
+```
+
+**Note:** The `--access public` flag is required for scoped packages (@projectmd/...) to make them publicly available.
+
+### Step 6: Verify Publication
+
+```bash
+# Check if the package is published
+npm view @projectmd/node-monitor
+
+# Try installing it
+npm install @projectmd/node-monitor
+```
+
+Visit your package page:
+```
+https://www.npmjs.com/package/@projectmd/node-monitor
+```
+
+---
+
+## 🔄 Updating the Package (Future Versions)
+
+### Update Version Number
+
+Use semantic versioning:
+
+```bash
+# Patch release (1.0.0 → 1.0.1) - Bug fixes
+npm version patch
+
+# Minor release (1.0.0 → 1.1.0) - New features, backward compatible
+npm version minor
+
+# Major release (1.0.0 → 2.0.0) - Breaking changes
+npm version major
+```
+
+This will:
+1. Update `package.json` version
+2. Create a git commit
+3. Create a git tag
+
+### Publish the New Version
+
+```bash
+# After updating version
+npm publish --access public
+
+# Push changes to git
+git push
+git push --tags
+```
+
+---
+
+## 📋 What Gets Published?
+
+### ✅ Included Files:
+- `src/` - All source code
+- `package.json`
+- `package-lock.json`
+- `README.md`
+- `LICENSE`
+- `GETTING_STARTED.md`
+- `INSTALLATION.md`
+- `SETUP_GUIDE.md`
+- `QUICK_REFERENCE.md`
+- `ARCHITECTURE.md`
+- `CHANGELOG.md`
+- `CONTRIBUTING.md`
+
+### ❌ Excluded Files (via .npmignore):
+- `node_modules/`
+- `examples/node_modules/`
+- `examples/logs/`
+- `.env` files
+- `logs/`
+- Test files
+- IDE configuration
+- Development documentation
+
+---
+
+## 🔍 Verify Package Contents
+
+Before publishing, check what will be included:
+
+```bash
+# List all files that will be published
+npm pack --dry-run
+
+# Or create the package and inspect it
+npm pack
+tar -tzf projectmd-node-monitor-1.0.0.tgz
+```
+
+---
+
+## 🛠️ Troubleshooting
+
+### Issue: "You must be logged in to publish packages"
+**Solution:**
+```bash
+npm login
+npm whoami  # Verify login
+```
+
+### Issue: "Package name already exists"
+**Solution:**
+- Choose a different package name
+- Or use a scope: `@yourusername/node-monitor`
+
+### Issue: "You do not have permission to publish"
+**Solution:**
+- Make sure you're logged in as the correct user
+- For scoped packages, use `--access public`
+
+### Issue: "Package version already exists"
+**Solution:**
+```bash
+# Update version first
+npm version patch
+npm publish --access public
+```
+
+### Issue: "Package size too large"
+**Solution:**
+- Check `.npmignore` is working
+- Remove unnecessary files
+- Check with: `npm pack --dry-run`
+
+---
+
+## 🔐 Security Best Practices
+
+### Enable 2FA (Two-Factor Authentication)
+
+```bash
+# Enable 2FA for your npm account
+npm profile enable-2fa auth-and-writes
+```
+
+### Use npm Tokens for CI/CD
+
+```bash
+# Create an automation token
+npm token create --read-only
+```
+
+---
+
+## 📊 After Publishing
+
+### Monitor Your Package
+
+1. **npm Package Page:**
+   - https://www.npmjs.com/package/@projectmd/node-monitor
+   - View downloads, versions, dependencies
+
+2. **Check Package Health:**
+   ```bash
+   npm view @projectmd/node-monitor
+   ```
+
+3. **Track Downloads:**
+   - https://npm-stat.com/charts.html?package=@projectmd/node-monitor
+
+### Respond to Issues
+
+- Monitor GitHub issues
+- Respond to user questions
+- Fix bugs and release patches
+
+### Keep Documentation Updated
+
+- Update README.md with new features
+- Maintain CHANGELOG.md
+- Update version in documentation
+
+---
+
+## 🎉 Success!
+
+Once published, users can install your package with:
+
+```bash
+npm install @projectmd/node-monitor
+```
+
+And use it in their projects:
+
+```javascript
+const NodeMonitor = require('@projectmd/node-monitor');
+const monitor = new NodeMonitor();
+```
+
+---
+
+## 📝 Quick Reference Commands
+
+```bash
+# Login
+npm login
+
+# Test package
+npm pack
+
+# Dry run
+npm publish --dry-run --access public
+
+# Publish
+npm publish --access public
+
+# Update version
+npm version patch|minor|major
+
+# View package info
+npm view @projectmd/node-monitor
+
+# Unpublish (within 72 hours only)
+npm unpublish @projectmd/node-monitor@1.0.0
+```
+
+---
+
+## 🔗 Useful Links
+
+- **npm Documentation:** https://docs.npmjs.com/
+- **Semantic Versioning:** https://semver.org/
+- **npm Package Best Practices:** https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry
+- **npm CLI Commands:** https://docs.npmjs.com/cli/v9/commands
+
+---
+
+## ⚠️ Important Notes
+
+1. **You cannot unpublish after 72 hours** - Be sure before publishing!
+2. **You cannot reuse a version number** - Once published, it's permanent
+3. **Breaking changes require major version bump** - Follow semantic versioning
+4. **Test thoroughly before publishing** - Your users depend on it!
+
+---
+
+**Good luck with your npm package! 🚀**
+

package/node-monitor/QUICK_REFERENCE.md

@@ -0,0 +1,252 @@
+# Node Monitor - Quick Reference
+
+## Installation
+
+```bash
+npm install @projectmd/node-monitor
+```
+
+## Basic Setup (30 seconds)
+
+```javascript
+const express = require('express');
+const NodeMonitor = require('@projectmd/node-monitor');
+
+const monitor = new NodeMonitor();
+const app = express();
+
+app.use(monitor.requestLogger());
+app.get('/health', monitor.healthCheckEndpoint());
+app.use(monitor.notFoundHandler());
+app.use(monitor.errorMiddleware());
+
+const server = app.listen(3000, () => {
+  monitor.start();
+  monitor.setupGracefulShutdown(server);
+});
+```
+
+## Common Tasks
+
+### Enable Email Alerts
+
+```javascript
+const monitor = new NodeMonitor({
+  notifications: {
+    email: {
+      enabled: true,
+      host: 'smtp.gmail.com',
+      port: 587,
+      auth: { user: 'you@gmail.com', pass: 'app-password' },
+      recipients: ['admin@example.com']
+    }
+  }
+});
+```
+
+### Enable Slack Alerts
+
+```javascript
+const monitor = new NodeMonitor({
+  notifications: {
+    slack: {
+      enabled: true,
+      webhook: 'https://hooks.slack.com/services/YOUR/WEBHOOK',
+      channel: '#monitoring'
+    }
+  }
+});
+```
+
+### Monitor Database
+
+```javascript
+// MongoDB
+monitor.registerDatabase('mongodb', 'mongoose', mongoose.connection);
+
+// PostgreSQL
+monitor.registerDatabase('postgres', 'postgresql', pgPool);
+
+// MySQL
+monitor.registerDatabase('mysql', 'mysql', mysqlPool);
+
+// Redis
+monitor.registerDatabase('redis', 'redis', redisClient);
+```
+
+### Custom Health Check
+
+```javascript
+monitor.registerHealthCheck('api-check', async () => {
+  const response = await fetch('https://api.example.com/health');
+  return response.ok;
+});
+```
+
+### Send Custom Alert
+
+```javascript
+await monitor.notify('critical', 'Payment Failed', 
+  'Payment system is down', 
+  { errorCode: 'PAY_001' }
+);
+```
+
+### Async Route Handler
+
+```javascript
+app.get('/users', monitor.asyncHandler(async (req, res) => {
+  const users = await User.find();
+  res.json(users);
+}));
+```
+
+### Custom Error
+
+```javascript
+const error = NodeMonitor.createError('Not found', 404);
+throw error;
+```
+
+### Get Status
+
+```javascript
+const status = monitor.getStatus();
+console.log(status.system.cpu);
+console.log(status.databases);
+```
+
+## Environment Variables (Most Common)
+
+```env
+# App
+MONITOR_APP_NAME=my-app
+NODE_ENV=production
+
+# Thresholds
+MONITOR_CPU_THRESHOLD=80
+MONITOR_MEMORY_THRESHOLD=90
+MONITOR_ERROR_RATE_THRESHOLD=50
+
+# Email
+MONITOR_EMAIL_ENABLED=true
+MONITOR_EMAIL_HOST=smtp.gmail.com
+MONITOR_EMAIL_USER=you@gmail.com
+MONITOR_EMAIL_PASS=your-password
+MONITOR_EMAIL_RECIPIENTS=admin@example.com
+
+# Slack
+MONITOR_SLACK_ENABLED=true
+MONITOR_SLACK_WEBHOOK=https://hooks.slack.com/...
+```
+
+## Monitoring Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `/health` | Full health check |
+| `/health/info` | Basic info |
+| `/monitor/dashboard` | Complete dashboard |
+| `/monitor/status` | Current status |
+| `/monitor/system` | System info |
+| `/monitor/metrics` | Metrics history |
+
+## Alert Levels
+
+- **critical** - Server down, DB disconnected
+- **warning** - High CPU/memory, error spike
+- **info** - General information
+- **recovery** - Issue resolved
+
+## Default Thresholds
+
+- CPU: 80%
+- Memory: 90%
+- Error Rate: 50 errors/min
+- Response Time: 5000ms
+- Consecutive Failures: 3
+
+## Default Intervals
+
+- Health Check: 60 seconds
+- System Check: 5 minutes
+- Database Check: 2 minutes
+
+## Supported Databases
+
+- MongoDB (via Mongoose)
+- PostgreSQL
+- MySQL
+- Redis
+
+## Log Levels
+
+- error
+- warn
+- info
+- debug
+- verbose
+
+## Tips
+
+1. **Start simple** - Begin with basic error tracking, add features as needed
+2. **Test notifications** - Send test alerts before going to production
+3. **Adjust thresholds** - Fine-tune based on your app's normal behavior
+4. **Use cooldowns** - Prevent alert spam with appropriate cooldown periods
+5. **Monitor the monitor** - Check logs to ensure monitoring is working
+6. **Graceful shutdown** - Always call `setupGracefulShutdown(server)`
+
+## Common Patterns
+
+### Full Express Setup
+
+```javascript
+const monitor = new NodeMonitor({
+  app: { name: 'My App', version: '1.0.0' },
+  thresholds: { cpu: 75, memory: 85 },
+  notifications: { email: { /* config */ } }
+});
+
+app.use(express.json());
+app.use(monitor.requestLogger());
+
+// Routes
+app.get('/health', monitor.healthCheckEndpoint());
+app.get('/', (req, res) => res.json({ ok: true }));
+
+// Error handling
+app.use(monitor.notFoundHandler());
+app.use(monitor.errorMiddleware());
+
+const server = app.listen(3000, () => {
+  monitor.start();
+  monitor.setupGracefulShutdown(server);
+});
+```
+
+### Production Config
+
+```javascript
+const monitor = new NodeMonitor({
+  intervals: { health: 30000, system: 60000 },
+  thresholds: { cpu: 75, memory: 85, errorRate: 25 },
+  notifications: {
+    cooldown: 180000,
+    email: { enabled: true, /* ... */ },
+    slack: { enabled: true, /* ... */ }
+  },
+  logging: {
+    level: 'info',
+    format: 'json',
+    console: false
+  }
+});
+```
+
+## Need Help?
+
+- 📖 Full docs: `README.md`
+- 🔧 Setup guide: `SETUP_GUIDE.md`
+- 💡 Examples: `examples/express-app.js`
+- 🐛 Issues: GitHub Issues
+