Command Line Interface

def main(argv=None):
    """
    Main entry point for the honcho command-line interface.
    
    Parameters:
    - argv: list, optional command-line arguments (defaults to sys.argv)
    
    Raises:
    SystemExit: exits with appropriate return code
    """

def command_start(args):
    """
    Start the application processes from Procfile.
    
    Parameters:
    - args: argparse.Namespace, parsed command-line arguments
    
    Raises:
    CommandError: if Procfile is invalid or processes fail
    """

def command_run(args):
    """
    Run a single command using the application's environment.
    
    Parameters:
    - args: argparse.Namespace, parsed command-line arguments with argv
    
    Raises:
    SystemExit: exits with the command's return code
    """

def command_export(args):
    """
    Export Procfile to another process management format.
    
    Parameters:
    - args: argparse.Namespace, parsed arguments including format and location
    
    Raises:
    CommandError: if export fails or format is unsupported
    """

def command_check(args):
    """
    Validate a Procfile for syntax and format errors.
    
    Parameters:
    - args: argparse.Namespace, parsed command-line arguments
    
    Raises:
    CommandError: if Procfile is invalid
    """

def command_version(args):
    """
    Display honcho version information.
    
    Parameters:
    - args: argparse.Namespace, parsed command-line arguments
    """

def command_help(args):
    """
    Display help information for commands.
    
    Parameters:
    - args: argparse.Namespace, parsed arguments with optional task name
    """

class CommandError(Exception):
    """
    Exception raised for command execution errors.
    Used to signal errors that should result in non-zero exit codes.
    """
    pass

def map_from(args):
    """
    Create configuration mapping from command-line arguments, environment variables,
    environment files, and defaults.
    
    Parameters:
    - args: argparse.Namespace, parsed command-line arguments
    
    Returns:
    ChainMap: configuration mapping with precedence order
    """

import argparse

# Main parser
parser = argparse.ArgumentParser(
    'honcho',
    description='Manage Procfile-based applications'
)

# Common arguments shared across commands
def _add_common_args(parser, with_defaults=False):
    """
    Add common command-line arguments to parser.
    
    Parameters:
    - parser: argparse.ArgumentParser, parser to add arguments to
    - with_defaults: bool, whether to include default values
    """

honcho start [options] [process...]

# Start all processes
honcho start

# Start specific processes
honcho start web worker

# Start with custom concurrency
honcho start -c web=2,worker=3

# Start with custom port and environment
honcho start -p 8000 -e production.env

# Start quietly suppressing worker output
honcho start -q worker

honcho run [options] command [args...]

# Run database migration
honcho run python manage.py migrate

# Run with custom environment
honcho run -e production.env python manage.py collectstatic

# Run interactive shell
honcho run python manage.py shell

# Run with double-dash separator
honcho run -- python -c "print('hello world')"

honcho export [options] format location

# Export to systemd
honcho export systemd /etc/systemd/system

# Export with custom app name and user
honcho export systemd /tmp/services -a myapp -u myapp

# Export with concurrency settings
honcho export supervisord /etc/supervisor/conf.d -c web=2,worker=3

# Export to custom location with templates
honcho export upstart /etc/init -t /path/to/templates

honcho check [options]

# Check default Procfile
honcho check

# Check specific Procfile
honcho check -f Procfile.production

# Check Procfile in different directory
honcho check -d /path/to/app

honcho version

honcho help [command]

# Show general help
honcho help

# Show help for specific command
honcho help start
honcho help export

# Create a Procfile
cat > Procfile << EOF
web: python app.py
worker: python worker.py
scheduler: python scheduler.py
EOF

# Create environment file
cat > .env << EOF
DATABASE_URL=postgresql://localhost:5432/myapp
DEBUG=true
PORT=5000
EOF

# Check Procfile validity
honcho check

# Start all processes
honcho start

# Start with custom configuration
honcho start -c web=2,worker=1 -p 8000

# Development with debug output
honcho start --no-colour -e development.env

# Run database migrations
honcho run python manage.py migrate

# Run tests in app environment
honcho run pytest tests/

# Start specific services only
honcho start web redis

# Export to systemd for production
sudo honcho export systemd /etc/systemd/system \
  -a myapp \
  -u myapp \
  -l /var/log/myapp \
  -c web=4,worker=2

# Enable and start services
sudo systemctl enable myapp.target
sudo systemctl start myapp.target

# Check service status
sudo systemctl status myapp.target

# Environment variable
export PORT=3000

# Environment file
echo "PORT=4000" > .env

# Command line (highest precedence)
honcho start -p 5000  # Uses port 5000

# Common error scenarios and handling

try:
    # Command execution
    COMMANDS[args.command](args)
except CommandError as e:
    # User-facing errors (invalid Procfile, missing files, etc.)
    log.error(str(e))
    sys.exit(1)
except KeyboardInterrupt:
    # Graceful shutdown on Ctrl+C
    sys.exit(130)
except Exception as e:
    # Unexpected errors
    log.error(f"Unexpected error: {e}")
    sys.exit(1)

# Default configuration values
DEFAULTS = {
    'port': '5000',
    'procfile': 'Procfile',
}

# Environment variable mappings
ENV_ARGS = {
    'port': 'PORT',
    'procfile': 'PROCFILE',
}

# Base directory name for app naming
BASENAME = os.path.basename(os.getcwd())

# Command function mappings
COMMANDS = {
    'start': command_start,
    'run': command_run,
    'export': command_export,
    'check': command_check,
    'version': command_version,
    'help': command_help,
}