feat: Migrate from Makefile to Python CLI for Better Cross-Platform Distribution

[Dr0p42]

🚀 Migrate from Makefile to Python CLI for Better Cross-Platform Distribution

Summary

Replace our current Makefile-based development workflow with a Python CLI tool that can be distributed via PyPI as pip install abi-cli. The CLI will create new ABI projects and intelligently delegate to project-local CLI versions when working within an ABI project, providing seamless version management and project-specific tooling.

Problem Statement

Our current Makefile approach, while functional, creates several barriers to adoption:

🪟 Windows Compatibility Issues

• Windows users need WSL or additional tooling to run Make commands
• Inconsistent behavior across different shells and platforms
• Complex conditional logic required for platform-specific commands

📦 Distribution Challenges

• Users must clone the entire repository just to access development tools
• No version management for the tooling itself
• Manual setup processes that vary by environment
• Difficult to share common workflows across teams

🛠️ Limited Functionality

• Cryptic error messages with little context
• No interactive prompts or setup wizards
• Limited progress feedback for long-running operations
• No built-in help system or command completion
• No automatic tooling updates or version awareness

Proposed Solution

Create a hybrid CLI approach with global installation and project-local delegation:

# Global installation for project creation
pip install abi-cli

# Create new projects (clones ABI template with embedded CLI)
abi new-project my-ai-project
cd my-ai-project

# All subsequent commands use the project's local CLI automatically
abi dev api                    # Uses ./cli/abi (project-local version)
abi test run                   # Automatically delegated to local CLI
abi agents chat supervisor     # Project-specific agent configuration
abi update                     # Updates the project's CLI version

🔄 Smart CLI Delegation

The global CLI will:

1. Detect ABI projects: Check for .abi/ directory or abi.yaml config
2. Auto-delegate: Re-execute commands using the project's local CLI
3. Preserve context: Pass all arguments and environment to local CLI
4. Fallback gracefully: Use global CLI when not in an ABI project

Benefits

✅ Cross-Platform Native Support

• Works identically on Windows, macOS, and Linux
• No need for WSL or additional tools
• Consistent path handling and shell behavior

✅ Professional Distribution & Project Management

• Install anywhere with pip install abi-cli
• Project templates: abi new-project clones optimized ABI setup
• Version isolation: Each project uses its own CLI version
• Seamless delegation: Global CLI automatically uses project-local version
• Easy bootstrapping: Single command creates fully configured projects

✅ Enhanced Developer Experience

• Rich error messages with actionable suggestions
• Interactive setup wizards for new developers
• Progress bars and real-time status updates
• Built-in help and shell completion
• Colored output and modern terminal UI
• Automatic update checking: "New version available! Run abi update to upgrade."
• Smart version management with release notes
• Context-aware commands: CLI behavior adapts to project configuration

✅ Better Maintainability

• Python code can be unit tested (unlike Make targets)
• Easier to implement complex logic and error handling
• Plugin system for extensibility
• YAML-based configuration management
• Version consistency: Projects can pin specific CLI versions
• Isolated environments: No conflicts between different project requirements

Implementation Plan

🎯 Phase 1: Foundation

• Set up Click-based CLI framework for global CLI
• Create PyPI packaging configuration for global distribution
• Implement project detection and delegation logic
• Create ABI project template repository with embedded CLI
• Implement abi new-project command with git cloning

🎯 Phase 2: Command Migration & Local CLI

• Build project-local CLI with same interface as global CLI
• Migrate environment setup commands to local CLI
• Migrate development server commands to local CLI
• Migrate testing and code quality checks
• Add progress indicators and rich output
• Implement automatic update checking system for both global and local CLI

🎯 Phase 3: Advanced Features & Smart Delegation

• Perfect delegation mechanism (argument passing, environment preservation)
• Migrate data management commands (DVC, triplestore)
• Migrate agent interaction commands with project-specific configs
• Add interactive modes and wizards
• Implement plugin architecture for project-local extensions
• Add smart update notifications for project CLI versions

🎯 Phase 4: Release & Adoption

• Publish global CLI to PyPI as abi-cli
• Create and maintain ABI project template repository
• Update all documentation with new workflow
• Create migration guide for existing users
• Deprecate Makefile (with transition period)

Technical Stack

• Click: CLI framework and argument parsing
• Rich: Beautiful terminal output and progress bars
• PyYAML: Configuration file management
• Requests: HTTP operations (ollama, API calls)
• Docker SDK: Docker container management
• Packaging: Version comparison and update checking
• GitPython: For project template cloning and git operations

CLI Architecture

Global CLI (pip install abi-cli)

# Responsibilities:
# 1. Project creation (abi new-project)
# 2. Project detection and delegation
# 3. Fallback commands when not in project
# 4. Global configuration management

def main():
    if is_in_abi_project():
        delegate_to_local_cli(sys.argv[1:])
    else:
        run_global_command()

Project-Local CLI (./cli/abi or similar)

# Responsibilities:
# 1. All project-specific operations
# 2. Project configuration management
# 3. Environment-specific commands
# 4. Agent interactions with project context

Success Criteria

• Windows users can set up and use the project without WSL
• Installation reduced to a single pip install command
• Project creation simplified to abi new-project <name>
• Seamless CLI delegation with no user awareness of global vs local
• All current Makefile functionality preserved and enhanced
• Improved error messages and user guidance
• Faster onboarding for new developers
• Positive feedback from cross-platform testing
• Users automatically notified of updates with easy upgrade path
• Project-specific CLI versions work without conflicts

Additional Context

This migration addresses a significant barrier to adoption, particularly for Windows developers who currently need additional tooling. The hybrid approach provides the best of both worlds: easy global installation with project-specific tooling.

Project Template Strategy: The abi new-project command will clone a maintained template repository that includes:

• Pre-configured project structure
• Project-local CLI (same interface as global)
• Environment configuration files
• Documentation and examples
• Latest best practices and dependencies

Smart Delegation Pattern: Similar to how npx works in the Node.js ecosystem:

# User runs global command
$ abi dev api

# Global CLI detects project and delegates:
# -> Executes: ./venv/bin/python -m abi.cli dev api
# -> With same environment and arguments
# -> User sees seamless experience

Update Management: Both global and project CLI will check for updates:

CLI Updates:

💡 Your project's CLI (v1.8.0) can be updated to v1.9.0!
   • New features: Enhanced agent chat interface
   • Bug fixes: Windows path handling improvements
   
   Run 'abi update' to upgrade, or 'abi config set auto-update false' to disable notifications.

---

Labels: enhancement, cross-platform, developer-experience, distribution, project-management
Priority: Medium