hana-developer-cli-tool-example: Instructions file for GitHub Copilot

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
  }
}