fix: add click compatibility layer for CLI alias support

[cofin]

Summary

• Adds a compatibility layer (advanced_alchemy/utils/cli_tools.py) that provides click alias support across all environments
• The aliases parameter in click groups is a rich-click 1.9+ feature that causes TypeError when users have plain click or older rich-click
• Implements AliasedGroup class that mimics rich-click's alias handling for plain click
• Updates all CLI modules to use the new compatibility layer

Problem

Users encounter failures when using the CLI in these scenarios:

Scenario A: Plain click (no rich-click)

TypeError: __init__() got an unexpected keyword argument 'aliases'

Scenario B: Old rich-click (< 1.9.0)

TypeError: __init__() got an unexpected keyword argument 'aliases'

Solution

Created advanced_alchemy/utils/cli_tools.py with:

• AliasedGroup class that implements alias resolution for plain click
• group() and command() wrapper decorators that auto-select the appropriate class
• Detection constants (_RICH_CLICK_AVAILABLE, _RICH_CLICK_ALIASES_SUPPORTED)

Changes

File	Change
advanced_alchemy/utils/cli_tools.py	New compatibility module
tests/unit/test_utils/test_click.py	Unit tests for the module
advanced_alchemy/cli.py	Updated to use compatibility layer
advanced_alchemy/extensions/fastapi/cli.py	Updated to use compatibility layer
advanced_alchemy/extensions/flask/cli.py	Updated to use compatibility layer
advanced_alchemy/extensions/litestar/cli.py	Updated to use compatibility layer

Test plan

• Unit tests for AliasedGroup class
• Tests with mocked plain click (no rich-click)
• Tests with mocked old rich-click (< 1.9.0)
• Tests with new rich-click >= 1.9.0
• Type checking passes (mypy/pyright)
• Linting passes (ruff/pre-commit)

[codecov-commenter]

Codecov Report

❌ Patch coverage is 92.52336% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 80.61%. Comparing base (959adba) to head (ad008a2).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
advanced_alchemy/utils/cli_tools.py	92.07%	5 Missing and 3 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #645      +/-   ##
==========================================
+ Coverage   80.44%   80.61%   +0.17%     
==========================================
  Files          87       88       +1     
  Lines        6453     6553     +100     
  Branches      838      850      +12     
==========================================
+ Hits         5191     5283      +92     
- Misses        998     1003       +5     
- Partials      264      267       +3     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Harshal6927]

import datetime

from litestar import Litestar
from litestar.handlers.http_handlers.decorators import get
from sqlalchemy.orm import Mapped

from advanced_alchemy.base import UUIDBase
from advanced_alchemy.config import AsyncSessionConfig
from advanced_alchemy.extensions.litestar.plugins import SQLAlchemyAsyncConfig, SQLAlchemyPlugin


@get("/test")
async def test_handler() -> dict[str, str]:
    return {"message": "test"}


class AuthorModel(UUIDBase):
    __tablename__ = "author"
    name: Mapped[str]
    dob: Mapped[datetime.date]


session_config = AsyncSessionConfig(expire_on_commit=False)
alchemy_config = SQLAlchemyAsyncConfig(
    connection_string="sqlite+aiosqlite:///test.sqlite",
    session_config=session_config,
    create_all=True,
)


app = Litestar(
    route_handlers=[test_handler],
    plugins=[SQLAlchemyPlugin(config=alchemy_config)],
)

advanced-alchemy on  fix/cli-alias [$?] is 📦 v1.8.2 via 🐍 v3.10.18 (advanced-alchemy) 
❯ litestar db -h
Using Litestar app from app:app
                                                                                                                        
 Usage: litestar [OPTIONS] COMMAND [ARGS]...                                                                            
                                                                                                                        
╭─ Error ──────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ No such command 'db'.                                                                                                │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

advanced-alchemy on  fix/cli-alias [$?] is 📦 v1.8.2 via 🐍 v3.10.18 (advanced-alchemy) 
❯ litestar database -h
Using Litestar app from app:app
                                                                                                                        
 Usage: litestar database [OPTIONS] COMMAND [ARGS]...                                                                   
                                                                                                                        
 Manage SQLAlchemy database components.                                                                                 
 Aliases: db                                                                                                            
                                                                                                                        
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help  -h  Show this message and exit.                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ branches                    Show current branch points in the migration history                                      │
│ check                       Check if the target database is up to date                                               │
│ downgrade                   Downgrade database to a specific revision.                                               │
│ drop-all                    Drop all tables from the database.                                                       │
│ dump-data                   Dump specified tables from the database to JSON files.                                   │
│ edit                        Edit a revision file using $EDITOR                                                       │
│ ensure-version              Create the alembic version table if it doesn't exist                                     │
│ heads                       Show current available heads in the script directory                                     │
│ history                     List changeset scripts in chronological order                                            │
│ init                        Initialize migrations for the project.                                                   │
│ list-templates              List available Alembic migration templates                                               │
│ make-migrations             Create a new migration revision.                                                         │
│ merge                       Merge two revisions together, creating a new migration file                              │
│ show                        Show the revision denoted by the given symbol                                            │
│ show-current-revision       Shows the current revision for the database.                                             │
│ stamp                       Stamp the revision table with the given revision; don't run any migrations               │
│ upgrade                     Upgrade database to a specific revision.                                                 │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

[Harshal6927]

Its says Aliases: db but it is not working

[cofin]

@Harshal6927 Give it another look now

[provinzkraut]

This PR still causes TypeError: __init__() got an unexpected keyword argument 'aliases' on rich-click < 1.9. I've upgraded AA in a project an am now faced with this