📝 Improve best practices compliance (POSIX, Node.js standards)

Problem

The project follows many Node.js CLI best practices but is missing some standard conventions that improve user experience and compatibility.

Based on nodejs-cli-apps-best-practices and 2025 Node.js standards.

Missing Best Practices

1. No Top-Level --version Flag

Current: Version only shown via git gpt config subcommand
Expected: Standard -v, --version flag

# Current - not working
$ git gpt --version
# Invalid command

# Expected behavior
$ git gpt --version
0.10.2

$ git gpt -v
0.10.2

Implementation:

import { readFileSync } from 'fs'
import { fileURLToPath } from 'url'
import { dirname, join } from 'path'

const __filename = fileURLToPath(import.meta.url)
const __dirname = dirname(__filename)
const packageJson = JSON.parse(
  readFileSync(join(__dirname, 'package.json'), 'utf8')
)

program
  .name('git-gpt')
  .description('AI-powered Git commit message generator')
  .version(packageJson.version, '-v, --version', 'Output the version number')
  .helpOption('-h, --help', 'Display help for command')

2. No Node.js Version Enforcement

Current: Volta specifies v22.18.0, but no package.json enforcement
Risk: Users on old Node.js versions may encounter runtime errors

Add to package.json:

{
  "engines": {
    "node": ">=18.0.0"
  }
}

Why Node 18+:

• Native ES Modules support (required by project)
• Stable fetch API
• Updated OpenAI SDK requirements
• Long-term support (LTS)

3. Missing .editorconfig

Current: Only .prettierrc for formatting
Issue: Different editors may use different settings

Create .editorconfig:

# EditorConfig: https://editorconfig.org
root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

[*.{js,json,md,yml,yaml}]
indent_style = space
indent_size = 2

[*.md]
trim_trailing_whitespace = false

[package.json]
indent_size = 2

4. API Key Format Validation

Current: No validation of OpenAI API key format
Issue: Cryptic errors when invalid key is used

/**
 * Validates OpenAI API key format
 * @param {string} key - API key to validate
 * @returns {boolean} True if valid format
 */
function isValidOpenAIKey(key) {
  // OpenAI keys start with 'sk-' or 'sk-proj-'
  // Followed by alphanumeric characters
  return /^sk-[a-zA-Z0-9-_]{20,}$/.test(key)
}

// In open-api-key command
if (response.value) {
  if (!isValidOpenAIKey(response.value)) {
    console.error('❌ Invalid API key format.')
    console.error('   OpenAI keys should start with "sk-"')
    console.error('   Get your key at: https://platform.openai.com/api-keys')
    return
  }
  
  saveConfig({ apiKey: response.value })
  apiKey = response.value
  console.log('✅ API key saved to configuration.')
}

5. Environment Variable Validation

Current: Silent fallback to .env if config key missing
Better: Validate and provide clear guidance

/**
 * Gets OpenAI API key with validation and helpful errors
 * @returns {string} Valid API key
 * @throws {Error} If no key found or invalid format
 */
function getValidatedApiKey() {
  // Priority: config file > .env file
  const key = apiKey || process.env.OPENAI_API_KEY
  
  if (!key) {
    console.error('❌ No OpenAI API key found.')
    console.error('\nOptions:')
    console.error('  1. Set via command: git gpt open-api-key add')
    console.error('  2. Set in .env file: OPENAI_API_KEY=sk-...')
    console.error('\nGet your key at: https://platform.openai.com/api-keys')
    process.exit(1)
  }
  
  if (!isValidOpenAIKey(key)) {
    console.error('❌ Invalid OpenAI API key format.')
    console.error('   Keys should start with "sk-"')
    console.error('\nUpdate your key: git gpt open-api-key add')
    process.exit(1)
  }
  
  return key
}

6. Exit Code Standardization

Current: All errors exit with code 1
Better: Use standard exit codes

const EXIT_CODES = {
  SUCCESS: 0,
  GENERAL_ERROR: 1,
  INVALID_USAGE: 2,
  CONFIG_ERROR: 3,
  API_ERROR: 4,
  NETWORK_ERROR: 5,
  GIT_ERROR: 6,
}

// Usage
if (!gitDiff) {
  console.log('No changes to commit.')
  process.exit(EXIT_CODES.SUCCESS) // Not an error
}

if (error.status === 401) {
  console.error('Invalid API key')
  process.exit(EXIT_CODES.API_ERROR)
}

7. Signal Handling (Graceful Shutdown)

Current: No cleanup on SIGINT/SIGTERM
Better: Handle signals gracefully

// Graceful shutdown
process.on('SIGINT', () => {
  console.log('\n\n👋 Commit canceled by user.')
  process.exit(EXIT_CODES.SUCCESS)
})

process.on('SIGTERM', () => {
  console.log('\n\n👋 Process terminated.')
  process.exit(EXIT_CODES.SUCCESS)
})

// Cleanup on exit
process.on('exit', (code) => {
  // Cleanup temporary files if any
  // Close file handles if any
})

Implementation Checklist

High Priority

• Add --version / -v top-level flag
• Add engines field to package.json
• Add API key format validation
• Improve environment variable error messages

Medium Priority

• Create .editorconfig file
• Standardize exit codes
• Add signal handling (SIGINT, SIGTERM)

Low Priority

• Add --help customization for each command
• Consider adding --quiet / -q flag for scripting
• Consider adding --dry-run flag to preview message

Benefits

• ✅ Better user experience
• ✅ Standard CLI conventions
• ✅ Cross-platform compatibility
• ✅ Better error messages
• ✅ Easier debugging

Acceptance Criteria

• git gpt --version works
• git gpt -v works
• Node.js version checked on install
• API key format validated on save
• .editorconfig created
• Exit codes standardized
• Signal handling implemented
• Tests updated for new behavior
• Documentation updated

Priority

Low-Medium - Nice to have, improves polish

Related

Quality analysis report: claudedocs/quality-analysis-report.md section 6

References

• Node.js CLI Best Practices
• POSIX Utility Conventions
• EditorConfig
• Standard Exit Codes

Start by reviewing claudedocs/quality-analysis-report.md section 6 and the package.json configuration, then locate the CLI entry point and existing command tests. Break the checklist into separately testable changes covering version handling, Node.js enforcement, API-key validation, editor configuration, exit codes, and signal handling. Done means the listed acceptance commands and behaviors work, with tests and documentation updated.