refactor: Convert main() coroutine to Click CLI group for extensible subcommands

[michaelos443]

Summary

This PR converts the free-standing main() coroutine into a proper Click group structure, enabling extensible subcommands without touching the main logic.

Changes

Core Changes

1. cli/cli_app.py - Main CLI restructuring:

   • Added import click for CLI framework
   • Renamed main() → run_interactive_cli() (the actual async function)
   • Created @click.group() decorator for cli() function as the main entry point
   • Added invoke_without_command=True so running without a subcommand defaults to interactive mode
   • Added @cli.command() for run subcommand (runs interactive session)
   • Added @cli.command() for config subcommand (placeholder for future configuration management)
   • Added @cli.command() for clean subcommand with options --cache, --logs, --all

2. cli/init.py - Updated exports:

   • Changed from from .cli_app import main as cli_main
   • To from .cli_app import cli, run_interactive_cli
   • Updated __all__ accordingly

3. cli/cli_launcher.py - Updated to use Click:

   • Changed from from cli.cli_app import main as cli_main and asyncio.run(cli_main())
   • To from cli.cli_app import cli and cli(["run"])

4. requirements.txt - Added dependency:

   • Added click>=8.0.0 to the dependencies list

5. cli/CLI_COMMANDS.md - Created documentation:

   • Comprehensive guide on using the new CLI structure
   • Examples of all commands
   • Instructions for adding new subcommands
   • Migration notes for developers

Usage Examples

# Run interactive session (all equivalent):
python cli/cli_app.py
python cli/cli_app.py run

# View configuration (placeholder):
python cli/cli_app.py config

# Clean temporary files:
python cli/cli_app.py clean --cache
python cli/cli_app.py clean --logs
python cli/cli_app.py clean --all

# Get help:
python cli/cli_app.py --help
python cli/cli_app.py clean --help

# Version info:
python cli/cli_app.py --version

Benefits

✅ Extensible: Easy to add new subcommands like deepcode config, deepcode clean, deepcode doctor, etc.
✅ Professional: Uses industry-standard Click framework
✅ Backward Compatible: Existing workflows continue to work
✅ Self-Documenting: Built-in --help for all commands
✅ Clean Separation: Main logic untouched, only CLI structure changed

Future Enhancements

Potential subcommands to add:

• deepcode process --file <path> - Direct file processing
• deepcode process --url <url> - Direct URL processing
• deepcode history - View processing history
• deepcode export - Export results
• deepcode doctor - Check system dependencies and configuration

Testing

The changes have been tested to ensure:

• No import errors
• Click group structure works correctly
• Default behavior (running without subcommand) launches interactive session
• All subcommands are accessible and functional
• Help text is properly displayed

Related Issues

None

Checklist

• Code follows the project's style guidelines
• Changes are backward compatible
• Documentation has been updated
• No breaking changes to existing functionality
• All imports are properly organized

---

Pull Request opened by Augment Code with guidance from the PR author