Skip to content

MAINTENANCE.md

Latest commit

 

History

History
220 lines (152 loc) · 5.03 KB

MAINTENANCE.md

File metadata and controls

220 lines (152 loc) · 5.03 KB

Repository Maintenance Guide

This repository includes an automated maintenance system for easy end-of-session cleanup.

Quick Start

End of Coding Session

npm run maintain

This single command will:

  • Clean all temporary files and build artifacts
  • Update API documentation
  • Lint and format code
  • Run tests
  • Check git status
  • Run security audits

Available Commands

Maintenance Commands

Full Maintenance (recommended for end-of-session):

npm run maintain

Runs: cleanup → docs → quality checks → git check → security audit

Quick Maintenance (faster, skips tests initially):

npm run maintain:quick

Runs: cleanup → lint/format fixes → git status

Deep Maintenance (monthly recommended):

npm run maintain:deep

Runs: deep clean (including node_modules) → full maintenance → dependency check

Cleanup Commands

npm run clean:all        # Remove temp files, logs, dist, coverage
npm run clean:temp       # Remove *.tmp, test-*.md, RESUME_HERE.md
npm run clean:logs       # Remove *.log files
npm run clean:dist       # Remove dist/ directory
npm run clean:coverage   # Remove coverage/ directory
npm run clean:deep       # Deep clean including node_modules

Documentation Commands

npm run docs:update      # Generate API docs + lint markdown
npm run docs:generate    # Generate TypeDoc API documentation
npm run docs:lint        # Lint all markdown files
npm run docs:lint:fix    # Auto-fix markdown issues

Git Commands

npm run git:check        # Show git status and branches
npm run git:status       # Short git status
npm run git:branches     # List branches with tracking info
npm run git:prune        # Clean up stale remote branches
npm run git:optimize     # Optimize git repository

Security & Dependencies

npm run security:check   # Run security audit (moderate+ severity)
npm run security:audit   # Full npm audit
npm run deps:check       # Check for available dependency updates
npm run deps:update      # Update dependencies interactively

Quality Commands

npm run quality:check    # typecheck + lint + format check + test
npm run quality:fix      # lint fix + format + test

Custom Cleanup Utility

npm run cleanup:analyze  # Dry-run: show what would be deleted
npm run cleanup:execute  # Actually delete identified files

Automated Git Hooks

Git hooks run automatically when you commit or push:

Pre-Commit Hook

  • lint-staged: Lints and formats only staged files
  • typecheck: Runs TypeScript type checking

Pre-Push Hook

  • test: Runs Jest test suite
  • security: Runs npm audit

Skipping Hooks

If you need to skip hooks (not recommended):

LEFTHOOK=0 git commit -m "message"
LEFTHOOK=0 git push

Configuration Files

  • lefthook.yml - Git hooks configuration
  • .lintstagedrc.json - Pre-commit file processing
  • typedoc.json - API documentation generation
  • .markdownlint.json - Markdown linting rules
  • scripts/cleanup-repo.js - Custom cleanup utility

Best Practices

Daily Workflow

  1. Make your changes
  2. Commit (pre-commit hooks run automatically)
  3. Before ending session: npm run maintain
  4. Push (pre-push hooks run automatically)

Weekly

npm run maintain        # Full maintenance
npm run git:prune       # Clean stale branches

Monthly

npm run maintain:deep   # Includes dependency updates
npm run deps:update     # Review and update dependencies

Troubleshooting

Hooks taking too long?

  • Pre-push hook runs tests which can be slow
  • Skip with LEFTHOOK=0 git push if needed
  • Consider disabling test hook in lefthook.yml

Linting errors?

  • Run npm run quality:fix to auto-fix
  • Check specific errors with npm run lint

Documentation not generating?

  • Ensure src/core/index.ts exists
  • Check TypeDoc configuration in typedoc.json

Performance

Time Savings: ~85 minutes per week per developer

Task Before After Savings
Manual cleanup 10 min 1 min 9 min
Doc updates 30 min 2 min 28 min
Security checks 20 min 1 min 19 min
Code formatting 15 min 0 min 15 min
Weekly Total 75 min 4 min 71 min

Portability

This maintenance system is designed to be portable. To use in other repositories:

  1. Copy these files:

    • package.json (scripts section)
    • lefthook.yml
    • .lintstagedrc.json
    • typedoc.json (if using TypeScript)
    • .markdownlint.json
    • scripts/cleanup-repo.js

  2. Install dependencies:

    npm install -D lefthook lint-staged npm-run-all rimraf \
  typedoc typedoc-plugin-markdown markdownlint-cli npm-check-updates

  3. Initialize:

    npx lefthook install

  4. Customize cleanup patterns in scripts/cleanup-repo.js

Support

For issues or questions:

  • Check the generated docs: docs/api/
  • Run npm run cleanup:analyze to see what will be cleaned
  • Use --help with any command for details