hana-developer-cli-tool-example automation-script-development.instructions.md

Automation Script Development Guidelines

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

Scope and Purpose

This guide applies to automation and code generation scripts in the scripts/ folder:

Script Categories:

• scripts/generate-*.js - Generate new files (docs, config, examples)
• scripts/enhance-*.js - Enhance existing files with extracted metadata
• scripts/update-*.js - Update existing files with new content
• scripts/populate-*.js - Populate templates with data
• scripts/CHANGELOG.js - Generate changelog from JSON

Common Scripts:

• scripts/generate-command-docs.js - Generate command documentation
• scripts/generate-sidebar-config.js - Generate VitePress sidebar config
• scripts/generate-examples.js - Generate example files
• scripts/enhance-command-docs.js - Enhance docs with metadata from source
• scripts/update-epilogues.js - Update command epilogues
• scripts/populate-command-docs.js - Populate doc templates
• scripts/CHANGELOG.js - Convert CHANGELOG.json to markdown

Critical Principles

1. Shebang: Start with #!/usr/bin/env node for direct execution
2. ESM Modules: Use ES module syntax (import/export)
3. Type Safety: Add @ts-check for basic type checking
4. Safe File I/O: Check existence before reading, backup before overwriting
5. Clear Logging: Provide progress updates and success/failure messages
6. Exit Codes: Use proper exit codes (0=success, 1=failure)
7. Idempotency: Scripts should be safe to run multiple times
8. Documentation: Include JSDoc header explaining purpose

File Structure Template

#!/usr/bin/env node
/**
 * Brief description of what this script does
 * 
 * Usage: node script-name.js [options]
 * 
 * Examples:
 *   node script-name.js
 *   node script-name.js --force
 */

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

// Node 20.11+: import.meta.dirname / import.meta.filename
const __dirname = import.meta.dirname

// Constants
const SOURCE_DIR = path.join(__dirname, 'source')
const OUTPUT_DIR = path.join(__dirname, 'output')

/**
 * Main execution function
 */
async function main() {
    try {
        console.log('Starting script...')
        
        // Script logic here
        
        console.log('✅ Script completed successfully')
        process.exit(0)
    } catch (error) {
        console.error('❌ Script failed:', error.message)
        console.error(error.stack)
        process.exit(1)
    }
}

main()