1  ---
  2  title: 'Maintenance'
  3  category: 'operations'
  4  last_verified: '2026-02-15'
  5  related_files:
  6    - 'src/mvp.js'
  7    - 'scripts/maintenance/dashboard.js'
  8    - 'scripts/maintenance/backup-db.sh'
  9  tags: ['maintenance', 'cron', 'scheduling', 'testing', 'security', 'database', 'api', 'ai']
 10  status: 'current'
 11  ---
 12  
 13  # Maintenance Plan
 14  
 15  This document outlines regular maintenance tasks for the 333 Method automation project.
 16  
 17  ## Maintenance Schedule
 18  
 19  ### Daily (Automated)
 20  
 21  - Database backup (automated via cron)
 22  - Email events sync (automated via cron - every 5 minutes)
 23  
 24  ### Weekly (Manual Review)
 25  
 26  - Review Dependabot PRs for dependency updates
 27  - Check npm vulnerabilities
 28  - Review test coverage metrics
 29  - Check for stale branches
 30  
 31  ### Monthly (Manual Tasks)
 32  
 33  - Database maintenance (integrity, optimization)
 34  - Documentation audit
 35  - Unused code review
 36  - Security audit
 37  - API quota monitoring
 38  
 39  ### Quarterly (Strategic Review)
 40  
 41  - Architecture review
 42  - Performance optimization assessment
 43  - Test strategy review
 44  - Compliance audit (CAN-SPAM, TCPA)
 45  
 46  ---
 47  
 48  ## Task Checklists
 49  
 50  ### 1. Dependency Management
 51  
 52  **Frequency:** Weekly
 53  
 54  **Tools:**
 55  
 56  - Dependabot (configured for weekly checks)
 57  - npm audit
 58  - npm outdated
 59  
 60  **Checklist:**
 61  
 62  ```bash
 63  # Check for vulnerabilities
 64  npm audit
 65  
 66  # Review outdated packages
 67  npm outdated
 68  
 69  # Check Dependabot PRs on GitHub
 70  gh pr list --label "dependencies"
 71  
 72  # If vulnerabilities found, fix automatically when safe
 73  npm audit fix
 74  
 75  # For breaking changes, test thoroughly
 76  npm audit fix --force  # Only after manual review
 77  npm test && npm run quality-check
 78  ```
 79  
 80  **Decision Point:**
 81  
 82  - Auto-merge Dependabot PRs for patch/minor updates after CI passes
 83  - Require human review for major version updates
 84  - Require human review for any updates to core dependencies (playwright, better-sqlite3)
 85  
 86  **Snyk Integration:**
 87  
 88  - Current: Dependabot handles dependency updates and security alerts
 89  - Recommendation: Dependabot is sufficient for this project's needs
 90  - Consider Snyk if: team grows, commercial deployment, or need advanced vulnerability intelligence
 91  
 92  ---
 93  
 94  ### 2. Code Quality
 95  
 96  **Frequency:** Before each commit (automated) + Weekly review
 97  
 98  **Tools:**
 99  
100  - ESLint
101  - Prettier
102  - c8 (coverage)
103  - Sage AI
104  
105  **Checklist:**
106  
107  ```bash
108  # Run full quality check (includes Sage AI review)
109  npm run quality-check
110  
111  # Check coverage metrics
112  npm test
113  # Open coverage/index.html to review
114  
115  # Identify uncovered code
116  npm test 2>&1 | grep "% Funcs"
117  
118  # Check for ESLint warnings that should be fixed
119  npm run lint
120  ```
121  
122  **Coverage Targets:**
123  
124  - Minimum: 70% (current: 68.5%)
125  - New modules: 80%+
126  - Critical paths (scoring, outreach, payments): 90%+
127  
128  **Decision Points:**
129  
130  - Flag functions with <50% coverage for human review
131  - Flag files with complexity >15 for potential refactoring
132  - Flag files >300 lines for potential splitting
133  
134  ---
135  
136  ### 3. Database Maintenance
137  
138  **Frequency:** Monthly or after major operations
139  
140  **Tools:**
141  
142  - SQLite built-in commands
143  - DBeaver for inspection
144  
145  **Checklist:**
146  
147  ```bash
148  # Backup first (ALWAYS!)
149  cp db/sites.db "db/backup/sites-backup-$(date +%Y%m%d-%H%M%S).db"
150  
151  # Integrity check
152  sqlite3 db/sites.db "PRAGMA integrity_check;"
153  
154  # Database statistics
155  sqlite3 db/sites.db "SELECT name, COUNT(*) FROM (
156    SELECT 'sites' as name FROM sites
157    UNION ALL SELECT 'outreaches' FROM outreaches
158    UNION ALL SELECT 'conversations' FROM conversations
159    UNION ALL SELECT 'keywords' FROM keywords
160    UNION ALL SELECT 'unsubscribed_emails' FROM unsubscribed_emails
161  ) GROUP BY name;"
162  
163  # Optimize query planner
164  sqlite3 db/sites.db "PRAGMA optimize;"
165  
166  # Analyze tables for better query planning
167  sqlite3 db/sites.db "ANALYZE;"
168  
169  # Reclaim unused space (locks database briefly)
170  sqlite3 db/sites.db "VACUUM;"
171  
172  # Check database size
173  ls -lh db/sites.db
174  ```
175  
176  **Decision Points:**
177  
178  - Run VACUUM if database >100MB and has significant deletes
179  - Review and archive old data (>6 months) if database >500MB
180  - Flag for human review: corrupted sites, orphaned records, suspicious patterns
181  
182  **Monitoring Metrics:**
183  
184  - Database file size
185  - Number of sites per status
186  - Failed outreach ratio
187  - Average response time
188  
189  ---
190  
191  ### 4. Documentation Audit
192  
193  **Frequency:** Monthly
194  
195  **Files to Review:**
196  
197  - `README.md` - Central command reference
198  - `CLAUDE.md` - AI assistant instructions
199  - `../TODO.md` - Implementation status
200  - `../02-architecture/architecture.md` - System design
201  - `docs/BEST-PRACTICES-*.md` - Compliance guides
202  - `.env.example` - Environment variables
203  
204  **Checklist:**
205  
206  ```bash
207  # Check for outdated command references
208  grep -r "npm run" README.md CLAUDE.md | sort -u > /tmp/docs-cmds.txt
209  npm run | grep "^  " | awk '{print $1}' | sort -u > /tmp/package-cmds.txt
210  diff /tmp/docs-cmds.txt /tmp/package-cmds.txt
211  
212  # Verify all environment variables documented
213  grep -h "process.env" src/**/*.js | grep -o 'process.env\.[A-Z_]*' | sort -u > /tmp/code-vars.txt
214  grep -o "^[A-Z_]*=" .env.example | sed 's/=//' | sort -u > /tmp/example-vars.txt
215  diff /tmp/code-vars.txt /tmp/example-vars.txt
216  
217  # Check for broken internal links (manual review needed)
218  grep -r "\[.*\](.*\.md)" docs/ README.md CLAUDE.md
219  ```
220  
221  **Decision Points:**
222  
223  - Flag undocumented npm scripts for human review
224  - Flag undocumented environment variables for human review
225  - Flag inconsistencies between code and docs for human review
226  - Update version numbers and dates in docs
227  
228  ---
229  
230  ### 5. Unused Code Detection
231  
232  **Frequency:** Monthly
233  
234  **Tools:**
235  
236  - Manual inspection
237  - ESLint no-unused-vars
238  
239  **Checklist:**
240  
241  ```bash
242  # Find potentially unused exports
243  for file in src/**/*.js; do
244    exports=$(grep -o "export.*function [a-zA-Z0-9_]*\|export const [a-zA-Z0-9_]*" "$file" | awk '{print $NF}')
245    for exp in $exports; do
246      uses=$(grep -r "$exp" src/ tests/ | grep -v "export" | wc -l)
247      if [ "$uses" -lt 2 ]; then
248        echo "Potentially unused: $exp in $file (uses: $uses)"
249      fi
250    done
251  done
252  
253  # Find files with no test coverage
254  for file in src/**/*.js; do
255    testfile="tests/$(basename "$file" .js).test.js"
256    if [ ! -f "$testfile" ]; then
257      echo "No tests for: $file"
258    fi
259  done
260  
261  # Check for commented-out code (manual review)
262  grep -r "^[[:space:]]*\/\/" src/ | grep -v "\/\/ " | head -20
263  ```
264  
265  **Decision Points (Requires Human Review):**
266  
267  - Remove unused utility functions
268  - Remove deprecated features
269  - Remove commented-out code
270  - Archive old migrations (keep recent 10)
271  
272  ---
273  
274  ### 6. Security Audit
275  
276  **Frequency:** Monthly
277  
278  **Focus Areas:**
279  
280  - API key exposure
281  - SQL injection vectors
282  - XSS vulnerabilities
283  - SSRF risks
284  - Rate limiting
285  
286  **Checklist:**
287  
288  ```bash
289  # Check for hardcoded secrets
290  grep -r -i "api.key\|password\|secret\|token" src/ | grep -v "process.env" | grep -v "\.test\.js"
291  
292  # Check for SQL injection risks (should use parameterized queries)
293  grep -r "db.prepare.*\${" src/
294  
295  # Check for unsafe eval or exec
296  grep -r "eval\|exec\|Function(" src/
297  
298  # Verify rate limiting on external APIs
299  grep -r "fetch\|axios\|request" src/ | head -20
300  
301  # Check environment variable usage
302  grep -r "process.env\." src/ | grep -v "process.env\.[A-Z_]*[|?]"
303  ```
304  
305  **Decision Points:**
306  
307  - Flag any findings for immediate human review
308  - Schedule penetration testing if deploying commercially
309  - Review OWASP Top 10 compliance
310  
311  ---
312  
313  ### 7. Test Infrastructure
314  
315  **Frequency:** Weekly
316  
317  **Checklist:**
318  
319  ```bash
320  # Run full test suite
321  npm run test:all
322  
323  # Check for flaky tests (run 3 times)
324  for i in 1 2 3; do
325    echo "Run $i:"
326    npm test 2>&1 | grep -E "tests [0-9]+ pass"
327  done
328  
329  # Review test execution time
330  npm test 2>&1 | grep "duration"
331  
332  # Check for skipped tests
333  grep -r "test.skip\|test.todo" tests/
334  ```
335  
336  **Metrics to Track:**
337  
338  - Total tests
339  - Pass rate
340  - Average execution time
341  - Coverage percentage
342  - Flaky test count
343  
344  **Decision Points:**
345  
346  - Investigate any test taking >5 seconds
347  - Flag skipped tests for human review
348  - Add integration tests for new features
349  
350  ---
351  
352  ### 8. API Monitoring
353  
354  **Frequency:** Weekly
355  
356  **Services to Monitor:**
357  
358  - ZenRows (SERP scraping) - 1,000 req/day free
359  - OpenRouter (AI) - pay-per-use
360  - Resend (Email) - 100 emails/day free
361  - Twilio (SMS) - pay-per-use
362  - Cloudflare Workers (webhooks)
363  
364  **Checklist:**
365  
366  ```bash
367  # Check usage from database
368  sqlite3 db/sites.db "SELECT
369    DATE(created_at) as date,
370    COUNT(*) as sites_scraped
371  FROM sites
372  WHERE created_at > datetime('now', '-30 days')
373  GROUP BY date
374  ORDER BY date DESC;"
375  
376  sqlite3 db/sites.db "SELECT
377    DATE(sent_at) as date,
378    contact_method,
379    COUNT(*) as sent
380  FROM outreaches
381  WHERE sent_at > datetime('now', '-30 days')
382  GROUP BY date, contact_method
383  ORDER BY date DESC;"
384  
385  # Check for failed API calls in logs (if logging implemented)
386  # grep -i "error.*api\|rate limit\|quota" logs/*.log
387  
388  # Manually check dashboards:
389  # - ZenRows: https://app.zenrows.com/
390  # - OpenRouter: https://openrouter.ai/activity
391  # - Resend: https://resend.com/emails
392  # - Twilio: https://console.twilio.com/
393  # - Cloudflare: https://dash.cloudflare.com/
394  ```
395  
396  **Decision Points:**
397  
398  - Upgrade plan if consistently hitting limits
399  - Optimize usage patterns to stay within free tiers
400  - Set up alerts for approaching quota limits
401  
402  ---
403  
404  ### 9. Git Hygiene
405  
406  **Frequency:** Weekly
407  
408  **Checklist:**
409  
410  ```bash
411  # List stale branches (>30 days since last commit)
412  git for-each-ref --sort=-committerdate refs/heads/ --format='%(committerdate:short) %(refname:short)'
413  
414  # Check for large files in repo
415  git rev-list --objects --all | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | awk '/^blob/ {print $3, $4}' | sort -nr | head -20
416  
417  # Review recent commits for quality
418  git log --oneline -20
419  
420  # Check for accidentally committed secrets
421  git log -p | grep -i "api.key\|password\|secret" | head -10
422  ```
423  
424  **Decision Points:**
425  
426  - Delete merged branches
427  - Flag large files for human review (should they be in .gitignore?)
428  - Rewrite history if secrets found (nuclear option)
429  
430  ---
431  
432  ### 10. Performance Monitoring
433  
434  **Frequency:** Monthly
435  
436  **Metrics:**
437  
438  - Screenshot capture time
439  - AI scoring time
440  - Proposal generation time
441  - Email/SMS delivery time
442  - End-to-end pipeline time
443  
444  **Checklist:**
445  
446  ```bash
447  # Add timing to key operations (code enhancement needed)
448  # For now, manual timing:
449  time node src/mvp.js poc "test keyword" --limit 1
450  
451  # Database query performance
452  sqlite3 db/sites.db "EXPLAIN QUERY PLAN SELECT * FROM sites WHERE status = 'pending';"
453  
454  # Check for missing indexes
455  sqlite3 db/sites.db ".schema" | grep -i "index"
456  ```
457  
458  **Decision Points:**
459  
460  - Add indexes if queries consistently slow (>100ms)
461  - Optimize image sizes if screenshots >500KB
462  - Consider caching for AI prompts if costs high
463  
464  ---
465  
466  ## Automated Maintenance Scripts
467  
468  ### Proposed Scripts
469  
470  Create these in `scripts/maintenance/`:
471  
472  1. **`weekly-health-check.sh`**
473     - Run vulnerability scan
474     - Check outdated packages
475     - Generate coverage report
476     - Check database integrity
477     - Output summary report
478  
479  2. **`monthly-audit.sh`**
480     - Run full quality check
481     - Generate documentation diff report
482     - Detect unused code
483     - Security scan
484     - Database statistics
485  
486  3. **`pre-commit-hook.sh`** (git hook)
487     - Format code (Prettier)
488     - Lint code (ESLint)
489     - Run relevant tests
490     - Check for secrets
491  
492  4. **`backupDatabase`** (daily cron via `npm run cron`)
493     - Backup database with timestamp
494     - Automatic rotation: 7 daily + 4 weekly backups
495     - Deletes old backups automatically
496  
497  ---
498  
499  ## Maintenance Dashboard
500  
501  ### Proposed Tool: Simple Node.js CLI
502  
503  Create `scripts/maintenance/dashboard.js`:
504  
505  ```bash
506  node scripts/maintenance/dashboard.js
507  ```
508  
509  **Output:**
510  
511  ```
512  === 333 Method Maintenance Dashboard ===
513  
514  📦 Dependencies
515    • npm vulnerabilities: 0
516    • Outdated packages: 6
517    • Dependabot PRs: 0
518  
519  🧪 Code Quality
520    • Test coverage: 68.5% (target: 70%)
521    • ESLint issues: 12 warnings, 0 errors
522    • Uncovered modules: 3
523  
524  💾 Database
525    • Size: 45.3 MB
526    • Sites: 1,234
527    • Pending outreaches: 56
528    • Last backup: 2 hours ago
529  
530  📊 API Usage (Last 30 Days)
531    • SERP scrapes: 450/1000 (45%)
532    • Emails sent: 78/100/day avg
533    • SMS sent: 23 (~$0.17)
534  
535  🔐 Security
536    • Last audit: 14 days ago
537    • Critical issues: 0
538    • Warnings: 2 (review required)
539  
540  📚 Documentation
541    • Last updated: 3 days ago
542    • Sync issues: 1 (undocumented env var)
543  
544  ⚠️  Action Required
545    1. Update 6 outdated packages
546    2. Add tests for 3 modules (coverage <50%)
547    3. Review security warning in form.js
548  ```
549  
550  ---
551  
552  ## Human Approval Required
553  
554  These tasks MUST have human review before execution:
555  
556  1. **Major Version Updates**
557     - Core dependencies (Playwright, better-sqlite3)
558     - Breaking changes in any dependency
559  
560  2. **Code Deletion**
561     - Removing unused functions
562     - Deleting old migrations
563     - Removing deprecated features
564  
565  3. **Database Changes**
566     - VACUUM operation (locks database)
567     - Schema migrations
568     - Bulk deletions
569  
570  4. **Security Issues**
571     - Vulnerability fixes requiring code changes
572     - API key rotation
573     - Authentication changes
574  
575  5. **Configuration Changes**
576     - CI/CD modifications
577     - Git hooks
578     - ESLint rule changes
579  
580  6. **Breaking Changes**
581     - API contract changes
582     - CLI command modifications
583     - Environment variable changes
584  
585  ---
586  
587  ## Getting Started
588  
589  ### Immediate Actions
590  
591  1. Create maintenance scripts directory:
592  
593  ```bash
594  mkdir -p scripts/maintenance
595  ```
596  
597  2. Set up weekly reminder (personal calendar/task manager):
598     - Every Monday: Review Dependabot PRs + npm audit
599     - First of month: Run full maintenance checklist
600  
601  3. Implement automated backup (add to cron):
602  
603  ```bash
604  # Add to crontab (crontab -e)
605  0 2 * * * cd /home/jason/SyncThing.Code/333Method && scripts/maintenance/backup-db.sh
606  ```
607  
608  4. Create maintenance log:
609  
610  ```bash
611  mkdir -p docs/maintenance-logs
612  echo "# Maintenance Log" > docs/maintenance-logs/$(date +%Y-%m).md
613  ```
614  
615  ### Next Steps
616  
617  1. Review this plan and adjust frequencies based on project phase
618  2. Decide on maintenance dashboard implementation
619  3. Create automated scripts for repetitive tasks
620  4. Set up monitoring/alerting if deploying to production
621  5. Document any new maintenance procedures discovered
622  
623  ---
624  
625  ## Notes
626  
627  - This plan assumes a single developer or small team
628  - Adjust frequencies based on deployment stage (dev/staging/prod)
629  - Commercial deployment requires additional compliance monitoring
630  - Consider GitHub Actions for CI/CD automation of some tasks