hana-developer-cli-tool-example scripts-directory-development.instructions.md

Scripts Directory Development Guidelines

Use this guide when creating or modifying scripts in the scripts/ directory.

Scope and Purpose

This guide applies to maintenance and utility scripts in the scripts/ directory that support development, testing, and build processes:

Script Types:

• Postinstall scripts: Run after npm install (postinstall.js)
• Validation scripts: Check project integrity (validate-i18n.js)
• Build utilities: Generate documentation indices (build-docs-index.js)
• Test utilities: Process test output (run-test-output.js)

Critical Principles

1. Shebang: Start with #!/usr/bin/env node for npm script execution
2. Exit Codes: Use 0 (success), 1 (validation failure), 2 (error)
3. CI-Friendly: Detect and adapt to CI/CD environments
4. Quiet Mode: Support --quiet flag for minimal output
5. Internationalization: Use text bundles for user messages
6. Error Aggregation: Collect all errors before failing
7. Idempotent: Safe to run multiple times
8. Self-Contained: Don't require external setup

File Structure Template

#!/usr/bin/env node

/**
 * Script purpose and description
 * 
 * This script [what it does].
 * 
 * Usage: node scripts/script-name.js [--flag] [--option value]
 * 
 * Exit codes:
 *   0 = Success
 *   1 = Validation failures or warnings
 *   2 = Fatal error (file system, parsing, etc.)
 */

import fs from 'fs'
import path from 'path'

// ESM __dirname equivalent (Node 20.11+: import.meta.dirname / import.meta.filename)
const __dirname = import.meta.dirname

// Configuration
const CONFIG = {
    rootDir: path.join(__dirname, '..'),
    targetDir: path.join(__dirname, '..', 'target'),
    // ... other config
}

// Parse arguments
const args = process.argv.slice(2)
const options = {
    quiet: args.includes('--quiet'),
    fix: args.includes('--fix'),
    help: args.includes('--help') || args.includes('-h')
}

// State tracking
let errorCount = 0
let warningCount = 0
const errors = []
const warnings = []

/**
 * Log error and track it
 * @param {string} message - Error message
 */
function logError(message) {
    errorCount++
    errors.push(message)
    if (!options.quiet) console.error(`❌ ERROR: ${message}`)
}

/**
 * Log warning and track it
 * @param {string} message - Warning message
 */
function logWarning(message) {
    warningCount++
    warnings.push(message)
    if (!options.quiet) console.warn(`⚠️  WARNING: ${message}`)
}

/**
 * Log info message
 * @param {string} message - Info message
 */
function logInfo(message) {
    if (!options.quiet) console.log(`ℹ️  ${message}`)
}

/**
 * Main execution function
 */
async function main() {
    try {
        if (options.help) {
            printHelp()
            process.exit(0)
        }

        logInfo('Starting script...')
        
        // Script logic here
        
        // Report results
        if (errorCount > 0 || warningCount > 0) {
            console.log(`\n📊 Summary: ${errorCount} errors, ${warningCount} warnings`)
            process.exit(errorCount > 0 ? 1 : 0)
        }
        
        if (!options.quiet) console.log('✅ All checks passed')
        process.exit(0)
        
    } catch (error) {
        console.error('❌ Fatal error:', error.message)
        console.error(error.stack)
        process.exit(2)
    }
}

/**
 * Print help message
 */
function printHelp() {
    console.log(`
Usage: node scripts/script-name.js [options]

Options:
  --quiet     Minimal output, only errors
  --fix       Automatically fix issues if possible
  --help, -h  Show this help message

Exit Codes:
  0 = Success
  1 = Validation failures found
  2 = Fatal error occurred
    `)
}

main()