hana-developer-cli-tool-example cli-command-development.instructions.md

CLI Command Development Guidelines

Use this guide when creating or modifying CLI command files in the bin/ directory.

Scope and Purpose

This guide applies to all command files in bin/. Each file represents a single CLI command that users can execute via hana-cli <commandName>.

Critical Principles

1. Consistency: All commands follow the same structural pattern.
2. Type Safety: Use JSDoc and @ts-check for type checking.
3. Internationalization: All user-facing strings must come from i18n bundles.
4. Error Handling: Comprehensive try/catch with proper cleanup.
5. Database Connections: Use the centralized connection infrastructure.
6. Documentation Integration: Every command links to its documentation.

File Structure Template

Every CLI command file must follow this structure:

// @ts-check
import * as baseLite from '../utils/base-lite.js'
import { buildDocEpilogue } from '../utils/doc-linker.js'

export const command = 'commandName [param1] [param2]'
export const aliases = ['alias1', 'alias2']
export const describe = baseLite.bundle.getText("commandName")

export const builder = (yargs) => yargs.options(baseLite.getBuilder({
  // Command-specific options here
})).wrap(160).example(
  'hana-cli commandName --option value',
  baseLite.bundle.getText("commandNameExample")
).epilog(buildDocEpilogue('commandName', 'category', ['relatedCmd1', 'relatedCmd2']))

export let inputPrompts = {
  // Prompt schema here
}

export async function handler(argv) {
  const base = await import('../utils/base.js')
  base.promptHandler(argv, mainFunction, inputPrompts)
}

export async function mainFunction(prompts) {
  const base = await import('../utils/base.js')
  base.debug('mainFunction')
  try {
    base.setPrompts(prompts)
    const db = await base.createDBConnection()
    
    // Business logic here
    
    base.outputTableFancy(results)
    base.end()
    return results
  } catch (error) {
    await base.error(error)
  }
}