Context

  The MongoDB Database Experience (DBX) Python team maintains multiple related repositories including PyMongo, Django integrations, and various Python

  framework tools. Developers face challenges when working across these repositories:

    • Fragmented workflows: Each repository requires separate setup for virtual environments, dependency management, and testing

    • Context switching overhead: Developers must remember different commands and configurations for each repository

    • Inconsistent environments: Lack of standardization leads to "works on my machine" problems

    • Manual repetitive tasks: Cloning repos, setting up venvs, installing dependencies, and running tests requires multiple manual steps

  The tool is inspired by django-mongodb-cli and built with modern Python tooling (uv, just, ruff, pytest) to provide a standalone CLI that can be

  installed globally via pipx and used from anywhere. It emphasizes "de-siloing" development by providing a unified interface for common tasks across

  all DBX Python repositories.

Definition of done

  The task is complete when:

    1. Core Commands Implemented:

       • dbx config - Initialize and manage configuration (~/.config/dbx-python-cli/config.toml)

       • dbx clone - Clone repositories individually or by group with automatic installation

       • dbx env - Create/manage virtual environments (base, group-level, or repo-level)

       • dbx install - Install dependencies with support for extras and dependency groups

       • dbx test - Run pytest tests with keyword filtering

       • dbx list - List available repositories and groups

       • dbx status - Show git status across repositories

       • dbx branch - View and manage git branches

       • dbx just - Execute justfile commands in repositories

       • dbx project - Create Django projects with MongoDB backend templates

    2. Group-Based Organization:

       • Repositories organized into logical groups (e.g., "pymongo", "django")

       • Shared virtual environments per group

       • Bulk operations on all repos in a group

    3. Quality Standards Met:

       • ≥80% test coverage with pytest

       • All tests passing in CI/CD pipeline

       • Documentation built with Sphinx + Furo theme

       • Pre-commit hooks configured (prek + ruff)

       • Type hints where applicable

    4. Installation & Distribution:

       • Installable via pipx install git+https://github.com/aclark4life/dbx-python-cli.git

       • Entry point dbx command available globally

       • Works on macOS and Linux (Python 3.11+)

    5. Documentation Complete:

       • README with quick start guide

       • Sphinx docs covering all commands and features

       • Design documentation explaining architectural decisions

       • API reference documentation

Pitfalls

    1. Path Resolution Issues:

       • The tool must work from any directory, not just within a specific workspace

       • Careful handling of relative vs absolute paths, especially for base_dir configuration

       • Virtual environment paths must be correctly resolved for different scenarios (base, group, repo)

    2. Virtual Environment Complexity:

       • Three levels of venvs (base dir, group, repo) can confuse users

       • Must clearly communicate which venv is being used for each operation

       • Python path resolution when running commands in different contexts

    3. Git Operations:

       • Fork workflows require careful handling of origin vs upstream remotes

       • Branch switching must handle uncommitted changes gracefully

       • Bulk operations on multiple repos can fail partially - need good error handling

    4. Dependency Management:

       • uv's behavior differs from pip in subtle ways

       • PEP 735 dependency groups are new - not all projects support them

       • Monorepo structures (multiple packages in subdirectories) need special handling

    5. Cross-Platform Compatibility:

       • Shell activation scripts differ between platforms

       • Path separators and environment variables vary

       • Subprocess calls must handle platform differences

    6. Configuration Management:

       • Config file location (~/.config/dbx-python-cli/config.toml) must be created if missing

       • Merging user config with defaults requires careful logic

       • Repository metadata (URLs, groups) must stay in sync with actual repos

    7. Error Recovery:

       • Partial failures in bulk operations (e.g., cloning 5 repos, 1 fails)

       • Network failures during git clone operations

       • Missing dependencies (git, uv, just) must be detected early with helpful messages

    8. Scope Creep:

       • Tool should focus on common workflows, not replicate all git/pip functionality

       • Resist adding features that are better handled by existing tools

       • Keep the AI-first philosophy - simple commands that do the right thing

    9. Testing Challenges:

       • Integration tests require actual git operations and file system manipulation

       • Mocking subprocess calls can be brittle

       • Test isolation is critical - tests must not interfere with user's actual config

    10. Documentation Drift:

          • Keep README, Sphinx docs, and command help text in sync

          • Examples in docs must be tested and kept up-to-date

          • Design decisions should be documented for future maintainers