feat: Standardize CLI with best practices (--yes, --format, --dry-run)

[prosdev]

🎯 Overview

Enhance CLI commands with industry-standard patterns for better UX, CI/CD integration, and scriptability. Apply these improvements consistently across all CLI commands.

🚀 Improvements

1. Non-Interactive Mode

Add --yes / -y flag for CI/CD pipelines:

dev mcp install --cursor --yes
dev gh index --yes
dev init --yes

Benefit: Enable automation without prompts
Examples: npm, apt-get, brew

2. Machine-Readable Output

Add --format option for scripting:

dev mcp list --cursor --format json
dev gh search "bug" --format json
dev stats --format yaml

Benefit: Easy integration with scripts and tools
Examples: gh, kubectl, docker

3. Dry Run Mode

Add --dry-run for preview before execution:

dev mcp install --cursor --dry-run
# Output: Would create server 'dev-agent-my-repo' at ~/.cursor/mcp.json

dev gh index --dry-run
# Output: Would index 243 files, estimated 30s

Benefit: Safety for users, preview changes
Examples: terraform, apt-get, npm

4. Verbosity Levels

Add --verbose / --quiet / --debug:

dev mcp install --verbose   # Show all steps
dev mcp install --quiet     # Only errors
dev mcp install --debug     # Debug output with timings

Benefit: Better debugging and cleaner CI logs
Examples: npm, docker, gh

5. Exit Code Standards

Document and standardize exit codes:

0: Success
1: General error
2: Validation failed (missing index, invalid args)
3: File permission error
4: Network error (GitHub CLI)

Benefit: Scripts can handle errors appropriately
Examples: Unix convention, POSIX standards

6. Atomic File Writes

Improve config writing to prevent corruption:

// Current: Direct write (can corrupt on crash)
await fs.writeFile(configPath, JSON.stringify(config));

// Improved: Atomic write
await fs.writeFile(tempPath, JSON.stringify(config));
await fs.rename(tempPath, configPath); // Atomic on POSIX

Benefit: Never corrupt config files
Examples: npm, package managers

7. Config Path Override

Support custom config paths:

dev mcp install --cursor --config /custom/mcp.json
# Or via env var
CURSOR_MCP_CONFIG=/custom/mcp.json dev mcp install --cursor

Benefit: Testing, custom setups, multiple configs
Examples: Most CLIs support this

8. Progress Indicators

Add progress for long operations:

dev gh index
# ✓ Fetching issues (1.2s)
# ✓ Fetching PRs (0.8s)  
# ✓ Building vectors (2.3s)
# ✓ Saving to disk (0.1s)

Benefit: User feedback during long operations
Examples: npm, docker pull

📋 Implementation Plan

Phase 1: Essential (High Priority)

• Add --yes / -y flag to all interactive commands
• Add --format json to list/search commands
• Implement atomic file writes for config operations
• Document exit codes in README

Phase 2: Quality of Life (Medium Priority)

• Add --dry-run to mutating operations
• Add --verbose / --quiet / --debug flags
• Standardize exit codes across all commands
• Add progress indicators for slow operations (>2s)

Phase 3: Advanced (Low Priority)

• Support custom config paths via flag and env var
• Add config validation command
• Add health checking to list commands
• Export/import config for team sharing

🎯 Commands to Update

Apply patterns to:

• dev init
• dev index
• dev search
• dev gh index
• dev gh search
• dev mcp install/uninstall/list
• dev stats

✅ Acceptance Criteria

• All commands support --yes flag
• List/search commands support --format json
• Config writes are atomic (temp file + rename)
• Exit codes documented in CLI help
• All tests passing with new flags
• README documents all new options
• Consistent behavior across all commands

🧪 Testing

• Unit tests for each flag combination
• Integration tests for non-interactive mode
• Test atomic writes (simulate crashes)
• Test JSON output parsing

Priority: Medium
Estimate: 2-3 days
Complexity: Medium (affects many files but each change is small)

📚 References

• 12 Factor CLI Apps
• Command Line Interface Guidelines
• POSIX Utility Conventions