hana-developer-cli-tool-example package-json-scripts.instructions.md

Package.json Scripts Management Guidelines

Use this guide when creating or modifying npm scripts in package.json.

Scope and Purpose

This guide applies to npm script management in:

• Root package.json - Main project scripts
• Subproject package.json files (e.g., mcp-server/package.json)
• Workspace package.json files in monorepos

Critical Principles

1. Naming Convention: Use consistent, predictable script names
2. Category Prefixes: Group related scripts with prefixes (test:*, build:*, docs:*)
3. Cross-Platform: Write scripts that work on Windows, macOS, and Linux
4. Composability: Build complex scripts from simpler ones
5. Lifecycle Hooks: Use npm lifecycle scripts appropriately
6. Environment Variables: Handle variables safely and consistently
7. Documentation: Add comments in package.json for complex scripts
8. Exit Codes: Respect exit codes for CI/CD integration

Script Naming Conventions

Pattern: Standard Script Names

{
  "scripts": {
    // Development
    "start": "node index.js",        // Primary entry point
    "dev": "nodemon index.js",       // Development with watch
    "serve": "node server.js",       // Start server
    
    // Building
    "build": "tsc",                  // Main build
    "build:watch": "tsc --watch",    // Watch mode
    "prebuild": "npm run clean",     // Runs before build
    "postbuild": "npm run types",    // Runs after build
    
    // Testing
    "test": "mocha",                 // Run all tests
    "test:unit": "mocha tests/unit", // Unit tests only
    "test:integration": "mocha tests/integration",
    "test:watch": "mocha --watch",   // Watch mode
    "pretest": "npm run lint",       // Runs before test
    
    // Code Quality
    "lint": "eslint .",              // Lint all files
    "lint:fix": "eslint . --fix",    // Auto-fix
    "format": "prettier --write .",  // Format code
    "format:check": "prettier --check .",
    
    // Coverage
    "coverage": "nyc npm test",      // Generate coverage
    "coverage:report": "nyc report --reporter=html",
    "coverage:check": "nyc check-coverage",
    
    // Documentation
    "docs": "npm run docs:dev",      // Alias for main docs task
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs",
    
    // Cleaning
    "clean": "rimraf dist coverage .nyc_output types",
    "clean:all": "npm run clean && rimraf node_modules",
    
    // Utilities
    "validate": "npm run lint && npm run test",
    "prepare": "husky install"       // Lifecycle hook
  }
}