feat: add use_cli (Typer), use_api (FastAPI), use_db (SQLAlchemy+Alembic) optional configs

- New prompts: use_cli, use_api, use_db (all default false)
- Conditional deps in pyproject.toml: typer, fastapi/uvicorn, sqlalchemy/alembic
- Conditional [project.scripts] entry point: cli:app when use_cli, else main:main
- New justfile recipes: run (cli), serve (api), migrate/make-migration (db)
- New template files: cli.py, api/, db/, alembic/ (with env.py, script.py.mako, versions/)
- copilot-instructions.md updated with CLI/API/DB sections
- validate-template.yml: added validate-cli, validate-api, validate-db jobs
- _tasks cleanup: removes cli.py/api//db//alembic/ when respective flag is false

Co-Authored-By: Claude <noreply@anthropic.com>

Author: namitdeb739-aug

.github/workflows/validate-template.yml

@@ -93,3 +93,120 @@ jobs:
       - name: Test
         working-directory: /tmp/rendered-minimal
         run: uv run pytest -v
+
+  validate-cli:
+    name: Validate (use_cli)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: astral-sh/setup-uv@94527f2e458b27549849d47d273a16bec83a01e9 # v7
+        with:
+          version: "0.11.3"
+          python-version: "3.12"
+      - name: Configure git
+        run: |
+          git config --global user.name "CI"
+          git config --global user.email "ci@test.com"
+      - name: Render template (cli)
+        run: |
+          TEMPLATE_DIR=$(mktemp -d)
+          git archive HEAD | tar -C "$TEMPLATE_DIR" -xf -
+          uvx copier copy "$TEMPLATE_DIR" /tmp/rendered-cli \
+            --trust \
+            --defaults \
+            --overwrite \
+            --data project_name=cli-project \
+            --data description="A CLI project" \
+            --data author_name="Test Author" \
+            --data author_email="test@example.com" \
+            --data github_user=test-user \
+            --data use_cli=true
+      - name: Lint
+        working-directory: /tmp/rendered-cli
+        run: |
+          uv run ruff check src/ tests/
+          uv run ruff format --check src/ tests/
+      - name: Type check
+        working-directory: /tmp/rendered-cli
+        run: uv run mypy src/
+      - name: Test
+        working-directory: /tmp/rendered-cli
+        run: uv run pytest -v
+
+  validate-api:
+    name: Validate (use_api)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: astral-sh/setup-uv@94527f2e458b27549849d47d273a16bec83a01e9 # v7
+        with:
+          version: "0.11.3"
+          python-version: "3.12"
+      - name: Configure git
+        run: |
+          git config --global user.name "CI"
+          git config --global user.email "ci@test.com"
+      - name: Render template (api)
+        run: |
+          TEMPLATE_DIR=$(mktemp -d)
+          git archive HEAD | tar -C "$TEMPLATE_DIR" -xf -
+          uvx copier copy "$TEMPLATE_DIR" /tmp/rendered-api \
+            --trust \
+            --defaults \
+            --overwrite \
+            --data project_name=api-project \
+            --data description="An API project" \
+            --data author_name="Test Author" \
+            --data author_email="test@example.com" \
+            --data github_user=test-user \
+            --data use_api=true
+      - name: Lint
+        working-directory: /tmp/rendered-api
+        run: |
+          uv run ruff check src/ tests/
+          uv run ruff format --check src/ tests/
+      - name: Type check
+        working-directory: /tmp/rendered-api
+        run: uv run mypy src/
+      - name: Test
+        working-directory: /tmp/rendered-api
+        run: uv run pytest -v --cov=src --cov-report=xml
+
+  validate-db:
+    name: Validate (use_db)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: astral-sh/setup-uv@94527f2e458b27549849d47d273a16bec83a01e9 # v7
+        with:
+          version: "0.11.3"
+          python-version: "3.12"
+      - name: Configure git
+        run: |
+          git config --global user.name "CI"
+          git config --global user.email "ci@test.com"
+      - name: Render template (db)
+        run: |
+          TEMPLATE_DIR=$(mktemp -d)
+          git archive HEAD | tar -C "$TEMPLATE_DIR" -xf -
+          uvx copier copy "$TEMPLATE_DIR" /tmp/rendered-db \
+            --trust \
+            --defaults \
+            --overwrite \
+            --data project_name=db-project \
+            --data description="A DB project" \
+            --data author_name="Test Author" \
+            --data author_email="test@example.com" \
+            --data github_user=test-user \
+            --data use_db=true
+      - name: Lint
+        working-directory: /tmp/rendered-db
+        run: |
+          uv run ruff check src/ tests/
+          uv run ruff format --check src/ tests/
+      - name: Type check
+        working-directory: /tmp/rendered-db
+        run: uv run mypy src/
+      - name: Test
+        working-directory: /tmp/rendered-db
+        run: uv run pytest -v --cov=src --cov-report=xml

copier.yaml

@@ -99,6 +99,21 @@ use_iot:
   default: false
   help: Include IoT/embedded setup (serial, GPIO, MQTT drivers, device config)?
 
+use_cli:
+  type: bool
+  default: false
+  help: Include Typer CLI scaffold (commands, --help, rich output)?
+
+use_api:
+  type: bool
+  default: false
+  help: Include FastAPI REST API scaffold (routes, health endpoint, uvicorn serve)?
+
+use_db:
+  type: bool
+  default: false
+  help: Include SQLAlchemy 2 + Alembic (database session, migrations)?
+
 # --- Post-setup options ---
 
 init_dvc:
@@ -133,6 +148,12 @@ _tasks:
     when: "{{ not use_iot }}"
   - command: rm -f tests/test_drivers.py
     when: "{{ not use_iot }}"
+  - command: rm -f "src/{{ package_name }}/cli.py"
+    when: "{{ not use_cli }}"
+  - command: rm -rf "src/{{ package_name }}/api/"
+    when: "{{ not use_api }}"
+  - command: rm -rf "src/{{ package_name }}/db/" alembic/ alembic.ini
+    when: "{{ not use_db }}"
   - command: rm -rf docker/ .dockerignore
     when: "{{ use_docker == 'none' }}"
   - command: rm -f docker/Dockerfile.gpu

template/.github/copilot-instructions.md.jinja

@@ -24,6 +24,16 @@ just coverage    # pytest with coverage report{% if testing == 'full' %} (80% th
 just docs        # mkdocs serve (local preview)
 {%- endif %}
 just release patch|minor|major  # bump version, tag, push
+{%- if use_cli %}
+just run [args]          # run the CLI app
+{%- endif %}
+{%- if use_api %}
+just serve               # start API dev server (uvicorn --reload)
+{%- endif %}
+{%- if use_db %}
+just migrate             # apply pending DB migrations
+just make-migration "msg"  # generate migration from model diff
+{%- endif %}
 ```
 
 ## Code Style
@@ -123,6 +133,49 @@ just deploy <host>   # rsync src/ + restart systemd service (or docker pull + co
 - **GPIO**: use `gpiozero` — `Device.pin_factory = MockFactory()` in test fixtures for CI-safe testing
 {% endif %}
 
+{% if use_cli %}
+## CLI Development
+
+- **Commands live in** `src/{{ package_name }}/cli.py` — add `@app.command()` functions there
+- **Entry point**: `{{ project_name }} <command>` (configured in `pyproject.toml` `[project.scripts]`)
+- **Testing**: use `typer.testing.CliRunner` to invoke commands in tests; never call `app()` directly
+- **Output**: prefer `typer.echo()` for plain output, `rich.print()` for styled output
+- **Options vs Arguments**: use `typer.Option` for optional flags, `typer.Argument` for positional args
+
+```bash
+just run --help           # see available commands
+just run <command>        # run a specific command
+```
+{% endif %}
+{% if use_api %}
+## API Development
+
+- **Routes live in** `src/{{ package_name }}/api/routes/` — add new routers there and include them in `api/main.py`
+- **No business logic in routes** — routes call service functions; keep logic in `src/{{ package_name }}/`
+- **Testing**: use `fastapi.testclient.TestClient` with the `app` instance — no running server needed
+- **Health check**: `GET /health/` is always available; add domain routes under their own prefix
+
+```bash
+just serve               # start dev server at http://localhost:8000
+                         # API docs at http://localhost:8000/docs
+```
+{% endif %}
+{% if use_db %}
+## Database Development
+
+- **Models live in** `src/{{ package_name }}/db/models/` — subclass `Base` from `db/base.py`
+- **Session**: use `get_db()` from `db/session.py` as a dependency (or context manager)
+- **DATABASE_URL**: set in environment (defaults to `sqlite:///./{{ package_name }}.db` for local dev)
+- **Migrations**: always create a migration after changing models; never edit existing migrations
+
+```bash
+just make-migration "describe your change"   # auto-generate migration from model diff
+just migrate                                  # apply all pending migrations
+```
+
+- Alembic env is in `alembic/env.py` — models must be imported there to register with metadata
+{% endif %}
+
 ## What NOT to Do
 
 - Do not bypass `uv` with `pip install` — always use `uv add` or `uv run`

template/alembic.ini.jinja

@@ -0,0 +1,40 @@
+# Alembic configuration for {{ project_name }}
+[alembic]
+script_location = alembic
+file_template = %(year)d%(month).2d%(day).2d_%(rev)s_%(slug)s
+prepend_sys_path = .
+version_path_separator = os
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

template/alembic/env.py.jinja

@@ -0,0 +1,49 @@
+"""Alembic environment configuration."""
+
+import os
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy import engine_from_config, pool
+
+from {{ package_name }}.db.base import Base
+import {{ package_name }}.db.models  # noqa: F401 — import models to register with Base.metadata
+
+config = context.config
+
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+target_metadata = Base.metadata
+DATABASE_URL = os.environ.get("DATABASE_URL", "sqlite:///./{{ package_name }}.db")
+
+
+def run_migrations_offline() -> None:
+    """Run migrations without a live database connection."""
+    context.configure(
+        url=DATABASE_URL,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    """Run migrations with a live database connection."""
+    connectable = engine_from_config(
+        {"sqlalchemy.url": DATABASE_URL},
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+    with connectable.connect() as connection:
+        context.configure(connection=connection, target_metadata=target_metadata)
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

template/alembic/script.py.mako

@@ -0,0 +1,26 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

template/alembic/versions/.gitkeep

@@ -170,6 +170,26 @@ deploy host tag="latest":
 {% endif %}
 {% endif %}
 
+{% if use_cli %}
+# Run the CLI application
+run *args:
+    uv run {{ project_name }} {% raw %}{{ args }}{% endraw %}
+{% endif %}
+{% if use_api %}
+# Start the API development server
+serve:
+    uv run uvicorn {{ package_name }}.api.main:app --reload --host 0.0.0.0 --port 8000
+{% endif %}
+{% if use_db %}
+# Run all pending database migrations
+migrate:
+    uv run alembic upgrade head
+
+# Create a new migration (usage: just make-migration "add user table")
+make-migration message:
+    uv run alembic revision --autogenerate -m {% raw %}"{{ message }}"{% endraw %}
+{% endif %}
+
 # Clean build artifacts
 clean:
     rm -rf dist/ build/{% if use_docs %} site/{% endif %} .pytest_cache/{% if use_typecheck %} .mypy_cache/{% endif %} .ruff_cache/ htmlcov/