feat: extract bp CLI as a uv workspace member

Author: igorbenav

backend/pyproject.toml

@@ -108,6 +108,22 @@ ignore_missing_imports = true
 module = "sqlalchemy.ext.asyncio"
 ignore_errors = true
 
+[[tool.mypy.overrides]]
+module = "taskiq"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "taskiq.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "taskiq_redis"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "taskiq_aio_pika"
+ignore_missing_imports = true
+
 [tool.ruff]
 line-length = 128
 

backend/uv.lock

@@ -0,0 +1,48 @@
+# bp — FastAPI-boilerplate CLI
+
+`bp` is the developer/operator command-line tool for projects built on the
+FastAPI boilerplate. It generates deployment artifacts, helps prepare the
+runtime environment, and serves as the host for plugin commands and feature
+generators.
+
+## Install
+
+This package is part of the workspace. From the repo root:
+
+```bash
+uv sync                    # syncs the workspace; bp is available via `uv run bp`
+uv run bp --help
+```
+
+To install `bp` machine-wide so it works outside this repo:
+
+```bash
+uv tool install --editable ./cli
+bp --help
+```
+
+## What's here
+
+```
+cli/src/cli/
+├── app.py                 root Typer app + plugin discovery
+├── plugins.py             entry-point loaders for bp.commands and bp.features
+├── commands/              in-tree command sub-apps
+│   ├── deploy.py          bp deploy generate <mode>
+│   └── env.py             bp env gen-secret / bp env validate
+├── features/              feature framework (manifest, plan, installer)
+│   └── _builtins/         in-tree features
+│       └── deploy/        compose/Dockerfile templates for local/prod/nginx
+└── lib/                   shared helpers (project discovery, prompts, render)
+```
+
+## Plugin extension points
+
+Two kinds of plugins, kept deliberately separate:
+
+- `bp.commands` entry-point group — third-party Typer sub-apps mounted under
+  `bp <name>` (e.g. `bp aws deploy`).
+- `bp.features` entry-point group — code generators with a manifest that
+  `bp feature` can list, install, and remove.
+
+See `cli/src/cli/plugins.py` for the discovery contracts.

cli/README.md

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fastapi-boilerplate-cli"
+version = "0.1.0"
+description = "bp — developer/operator CLI for the FastAPI boilerplate. Hosts in-tree commands and discovers third-party plugins."
+authors = [{ name = "Benav Labs", email = "contact@benav.io" }]
+license = { text = "MIT" }
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "typer>=0.12",
+    "jinja2>=3.1",
+    "fastapi-boilerplate",
+]
+
+[project.scripts]
+bp = "cli.app:app"
+
+[tool.uv.sources]
+fastapi-boilerplate = { workspace = true }
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["*"]
+
+[tool.setuptools.package-data]
+"*" = ["*.j2", "*.toml", "*.conf"]
+
+[tool.ruff]
+line-length = 128
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+extend-select = ["UP006", "UP007", "UP035", "UP039"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["cli"]
+
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+warn_unused_ignores = true
+namespace_packages = true
+explicit_package_bases = true
+
+[[tool.mypy.overrides]]
+module = "infrastructure.*"
+ignore_missing_imports = true

cli/pyproject.toml

@@ -0,0 +1,12 @@
+"""bp — the FastAPI-boilerplate command-line tool.
+
+The CLI is a Typer application with two extension points:
+
+- `bp.commands` entry-point group: third-party packages can register
+  top-level Typer sub-apps that mount under `bp <name>`.
+- `bp.features` entry-point group: third-party packages can register
+  ``Feature`` instances that ``bp feature`` can list, install, and remove.
+
+In-tree commands and features live alongside this package and follow
+the same contracts as plugins.
+"""

cli/src/cli/__init__.py

@@ -0,0 +1,55 @@
+"""bp — root Typer application and entry point.
+
+Mounts in-tree command sub-apps and discovers third-party plugins.
+The shipped console script (``[project.scripts] bp``) targets
+``app`` directly.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from . import plugins as _plugins
+from .commands import deploy as _deploy_cmd
+from .commands import env as _env_cmd
+
+app = typer.Typer(
+    name="bp",
+    help="FastAPI-boilerplate command-line tool.",
+    no_args_is_help=True,
+    pretty_exceptions_show_locals=False,
+)
+
+# In-tree commands. Mounted before plugin discovery so a plugin can't
+# silently shadow a built-in by registering the same name.
+app.add_typer(_deploy_cmd.app, name="deploy", help="Generate deployment artifacts (Dockerfile, compose, nginx config).")
+app.add_typer(_env_cmd.app, name="env", help="Inspect and prepare the runtime environment.")
+
+
+def _mount_command_plugins() -> None:
+    """Mount external Typer sub-apps registered under ``bp.commands``."""
+    builtin_names = {"deploy", "env", "feature"}
+    for name, sub_app in _plugins.discover_command_plugins().items():
+        if name in builtin_names:
+            typer.secho(
+                f"warning: plugin command '{name}' shadows a built-in; ignoring.",
+                fg=typer.colors.YELLOW,
+                err=True,
+            )
+            continue
+        app.add_typer(sub_app, name=name)
+
+
+_mount_command_plugins()
+
+
+@app.callback()
+def _root() -> None:
+    """bp — FastAPI-boilerplate command-line tool."""
+    # Typer uses this docstring as the root help text. The body is
+    # intentionally empty: the callback exists so options like
+    # ``--install-completion`` work without arguments.
+
+
+if __name__ == "__main__":  # pragma: no cover
+    app()

cli/src/cli/app.py

@@ -0,0 +1,91 @@
+"""``bp deploy`` — generate deployment artifacts.
+
+Today this is just a wrapper around the in-tree ``deploy`` feature.
+Other deploy-adjacent commands (``bp deploy nginx-tls``, ``bp deploy
+github-actions``) can mount here as siblings.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from pathlib import Path
+
+import typer
+
+from ..features.installer import FeatureInstaller
+from ..features.registry import get_feature
+from ..lib.project import discover_project
+from ..lib.prompts import error, info
+
+app = typer.Typer(no_args_is_help=True, help="Generate deployment artifacts.")
+
+
+class DeployMode(StrEnum):
+    local = "local"
+    prod = "prod"
+    nginx = "nginx"
+
+
+@app.command("generate")
+def generate(
+    mode: DeployMode = typer.Argument(
+        ...,
+        help="Deployment mode to generate. Pick `local` for hot-reload dev, `prod` for "
+        "single-host production, `nginx` for production behind a reverse proxy.",
+    ),
+    output_dir: Path = typer.Option(
+        None,
+        "--output-dir",
+        "-o",
+        help="Where to write the compose file. Defaults to the repo root.",
+    ),
+    api_port: int = typer.Option(8000, "--api-port", help="Host port to publish the API on."),
+    workers: int = typer.Option(4, "--workers", help="Number of API workers (prod / nginx only)."),
+    force: bool = typer.Option(False, "--force", "-f", help="Overwrite existing files without asking."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Assume yes for all prompts."),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Show what would be written, don't touch disk."),
+) -> None:
+    """Generate ``docker-compose.yml`` (and ``nginx/default.conf`` for nginx mode)."""
+    project = discover_project(output_dir)
+    feature = get_feature("deploy")
+    if feature is None:  # pragma: no cover — built-in feature, always present
+        error("deploy feature is not registered.")
+        raise typer.Exit(code=1)
+
+    target_root = (output_dir or project.repo_root).resolve()
+    target_root.mkdir(parents=True, exist_ok=True)
+
+    params: dict = {
+        "mode": mode.value,
+        "api_port": api_port,
+        "workers": workers,
+        "compose_target": target_root / "docker-compose.yml",
+    }
+    if mode == DeployMode.nginx:
+        params["nginx_conf_target"] = target_root / "nginx" / "default.conf"
+
+    plan = feature.plan(params, project)
+
+    installer = FeatureInstaller(dry_run=dry_run, assume_yes=force or yes)
+    info(f"deploy: generating '{mode.value}' compose for {project.repo_root}")
+    result = installer.apply(plan)
+
+    if result.files_skipped:
+        info("")
+        info(f"{len(result.files_skipped)} file(s) skipped.")
+    if dry_run:
+        info("")
+        info("dry-run complete — no files were written.")
+        return
+
+    info("")
+    info("done. Next steps:")
+    if mode == DeployMode.local:
+        info("  docker compose up --build")
+    elif mode == DeployMode.prod:
+        info("  cp backend/.env.example backend/.env  # if you haven't already")
+        info("  docker compose up -d --build")
+    else:
+        info("  cp backend/.env.example backend/.env  # if you haven't already")
+        info("  docker compose up -d --build")
+        info("  curl -i http://localhost/api/v1/health")