create-awesome-python-app 0.2.6__tar.gz → 0.2.7__tar.gz

{create_awesome_python_app-0.2.6 → create_awesome_python_app-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: create-awesome-python-app
-Version: 0.2.6
+Version: 0.2.7
 Summary: Composable scaffolding CLI for production-ready Python apps
 Project-URL: Homepage, https://github.com/Create-Python-App/create-python-app
 Project-URL: Repository, https://github.com/Create-Python-App/create-python-app
@@ -42,6 +42,7 @@ From blank folder to a working FastAPI, Django, Celery, CLI, or uv workspace pro
 [![MegaLinter][megalinterbadge]][megalinterurl]
 [![Shellcheck][shellcheckbadge]][shellcheckurl]
 [![Commit Activity][commitactivitybadge]][commitactivityurl]
+[![Discord](https://img.shields.io/discord/1527933660764831825?label=Discord&logo=discord&logoColor=white)](https://discord.gg/dwFTsR7fK2)
 
 **[Official Site](https://create-awesome-python-app.vercel.app)** · [Templates](https://create-awesome-python-app.vercel.app/templates) · [Extensions](https://create-awesome-python-app.vercel.app/extensions) · [Docs](https://create-awesome-python-app.vercel.app/docs) · [GitHub](https://github.com/Create-Python-App/create-python-app) · [PyPI](https://pypi.org/project/create-awesome-python-app/)
 

{create_awesome_python_app-0.2.6 → create_awesome_python_app-0.2.7}/README.md

@@ -26,6 +26,7 @@ From blank folder to a working FastAPI, Django, Celery, CLI, or uv workspace pro
 [![MegaLinter][megalinterbadge]][megalinterurl]
 [![Shellcheck][shellcheckbadge]][shellcheckurl]
 [![Commit Activity][commitactivitybadge]][commitactivityurl]
+[![Discord](https://img.shields.io/discord/1527933660764831825?label=Discord&logo=discord&logoColor=white)](https://discord.gg/dwFTsR7fK2)
 
 **[Official Site](https://create-awesome-python-app.vercel.app)** · [Templates](https://create-awesome-python-app.vercel.app/templates) · [Extensions](https://create-awesome-python-app.vercel.app/extensions) · [Docs](https://create-awesome-python-app.vercel.app/docs) · [GitHub](https://github.com/Create-Python-App/create-python-app) · [PyPI](https://pypi.org/project/create-awesome-python-app/)
 

{create_awesome_python_app-0.2.6 → create_awesome_python_app-0.2.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "create-awesome-python-app"
-version = "0.2.6"
+version = "0.2.7"
 description = "Composable scaffolding CLI for production-ready Python apps"
 readme = "README.md"
 requires-python = ">=3.12"

{create_awesome_python_app-0.2.6 → create_awesome_python_app-0.2.7}/src/create_awesome_python_app/__init__.py

@@ -1,3 +1,3 @@
 """Create Awesome Python App CLI."""
 
-__version__ = "0.2.6"
+__version__ = "0.2.7"

{create_awesome_python_app-0.2.6 → create_awesome_python_app-0.2.7}/src/create_awesome_python_app/catalog.py

@@ -13,7 +13,6 @@ from typing import Any
 
 from create_python_app_core.paths import default_cache_dir, resolve_source
 from rich.console import Console
-from rich.table import Table
 
 from create_awesome_python_app import __version__
 from create_awesome_python_app.prompt_style import (
@@ -159,6 +158,17 @@ def validate_extension_compatibility(
         raise IncompatibleExtensionsError(pairs)
 
 
+@dataclass(frozen=True)
+class CategoryInfo:
+    """Catalog category with optional rich metadata (CNA parity)."""
+
+    slug: str
+    name: str
+    description: str = ""
+    details: str = ""
+    labels: tuple[str, ...] = ()
+
+
 def short_category_label(category_name: str) -> str:
     """Derive a compact badge label from a catalog category name."""
     stop_words = {"Applications", "Application", "Boilerplate"}
@@ -168,11 +178,48 @@ def short_category_label(category_name: str) -> str:
     return " ".join(words[:2]) or category_name
 
 
+def category_index(data: dict[str, Any]) -> dict[str, CategoryInfo]:
+    """Index categories by slug, including description/details/labels."""
+    out: dict[str, CategoryInfo] = {}
+    for raw in data.get("categories", []):
+        if not isinstance(raw, dict):
+            continue
+        slug = str(raw.get("slug", "")).strip()
+        if not slug:
+            continue
+        labels_raw = raw.get("labels", [])
+        labels = (
+            tuple(str(label) for label in labels_raw)
+            if isinstance(labels_raw, list)
+            else ()
+        )
+        out[slug] = CategoryInfo(
+            slug=slug,
+            name=str(raw.get("name", slug)),
+            description=str(raw.get("description", "")).strip(),
+            details=str(raw.get("details", "")).strip(),
+            labels=labels,
+        )
+    return out
+
+
+def get_category_data(data: dict[str, Any], slug: str) -> CategoryInfo | None:
+    return category_index(data).get(slug)
+
+
+def format_category_choice_title(info: CategoryInfo, extension_count: int) -> str:
+    """Human title for the interactive extension-category picker."""
+    noun = "extension" if extension_count == 1 else "extensions"
+    title = f"{info.name} ({extension_count} {noun})"
+    if info.description:
+        title = f"{title} — {info.description}"
+    if info.labels:
+        title = f"{title} · {', '.join(info.labels[:3])}"
+    return title
+
+
 def _category_map(data: dict[str, Any]) -> dict[str, str]:
-    return {
-        str(category.get("slug", "")): str(category.get("name", ""))
-        for category in data.get("categories", [])
-    }
+    return {slug: info.name for slug, info in category_index(data).items()}
 
 
 def _search_text(template: dict[str, Any], category_name: str) -> str:
@@ -344,9 +391,9 @@ CACHE_TTL_SECONDS = 3600
 FETCH_TIMEOUT_SECONDS = 10
 USER_AGENT = f"create-awesome-python-app/{__version__} (https://github.com/Create-Python-App/create-python-app)"
 
-_FIXTURE = (
-    Path(__file__).resolve().parents[4] / "fixtures" / "catalog" / "templates.json"
-)
+_AUTO_FIXTURE_DIR = Path(__file__).resolve().parents[4]
+_SENTINEL = object()
+_fixture_root_override: Path | None | object = _SENTINEL
 
 _memory_cache: dict[str, Any] | None = None
 _memory_ts: float = 0.0
@@ -360,13 +407,61 @@ def catalog_cache_path() -> Path:
     return default_cache_dir() / "catalog" / "templates.json"
 
 
+def resolve_fixture_root() -> Path | None:
+    """Resolve the repo root that contains ``fixtures/catalog/templates.json``.
+
+    Priority: ``CPA_FIXTURE_DIR`` → walk-up from package → ``cwd``.
+    """
+    if _fixture_root_override is not _SENTINEL:
+        return _fixture_root_override  # type: ignore[return-value]
+
+    env = os.environ.get("CPA_FIXTURE_DIR", "").strip()
+    if env:
+        return Path(env).expanduser().resolve()
+
+    def _has_fixture_catalog(root: Path) -> bool:
+        return (root / "fixtures" / "catalog" / "templates.json").is_file()
+
+    if _has_fixture_catalog(_AUTO_FIXTURE_DIR):
+        return _AUTO_FIXTURE_DIR
+
+    # Editable / site-packages layouts vary; walk up from this file.
+    for parent in Path(__file__).resolve().parents:
+        if _has_fixture_catalog(parent):
+            return parent
+
+    cwd = Path.cwd()
+    if _has_fixture_catalog(cwd):
+        return cwd
+    return None
+
+
+def set_fixture_root_for_tests(root: Path | None) -> None:
+    """Override fixture root (test helper)."""
+    global _fixture_root_override
+    _fixture_root_override = root
+
+
+def reset_fixture_root_for_tests() -> None:
+    global _fixture_root_override
+    _fixture_root_override = _SENTINEL
+
+
+def fixture_catalog_path() -> Path | None:
+    root = resolve_fixture_root()
+    if root is None:
+        return None
+    return root / "fixtures" / "catalog" / "templates.json"
+
+
 def _read_json_file(path: Path) -> dict[str, Any]:
     return json.loads(path.read_text(encoding="utf-8"))
 
 
 def _read_fixture() -> dict[str, Any]:
-    if _FIXTURE.is_file():
-        return _read_json_file(_FIXTURE)
+    path = fixture_catalog_path()
+    if path is not None and path.is_file():
+        return _read_json_file(path)
     return {"templates": [], "extensions": [], "categories": []}
 
 
@@ -417,6 +512,19 @@ def get_catalog_data(*, force_refresh: bool = False) -> dict[str, Any]:
     """Load templates.json from remote URL, disk cache, or local fixture."""
     global _memory_cache, _memory_ts
 
+    if os.environ.get("CPA_CATALOG_FIXTURE") == "1":
+        path = fixture_catalog_path()
+        if path is None or not path.is_file():
+            raise RuntimeError(
+                "Fixture mode is enabled (CPA_CATALOG_FIXTURE=1) but the fixture "
+                "root could not be resolved. Set CPA_FIXTURE_DIR to the repo root "
+                "containing fixtures/catalog/templates.json."
+            )
+        data = _read_fixture()
+        _memory_cache = data
+        _memory_ts = time.time()
+        return data
+
     if (
         not force_refresh
         and _memory_cache is not None
@@ -425,38 +533,33 @@ def get_catalog_data(*, force_refresh: bool = False) -> dict[str, Any]:
     ):
         return _memory_cache
 
-    if os.environ.get("CPA_CATALOG_FIXTURE") == "1":
-        data = _read_fixture()
-    else:
-        url = catalog_url()
-        try:
-            data = _fetch_remote(url)
-            _write_disk_cache(data)
-        except (
-            urllib.error.URLError,
-            TimeoutError,
-            OSError,
-            json.JSONDecodeError,
-        ) as err:
-            disk = _read_disk_cache()
-            if disk is not None:
+    url = catalog_url()
+    try:
+        data = _fetch_remote(url)
+        _write_disk_cache(data)
+    except (
+        urllib.error.URLError,
+        TimeoutError,
+        OSError,
+        json.JSONDecodeError,
+    ) as err:
+        disk = _read_disk_cache()
+        if disk is not None:
+            console.print(
+                "[yellow][cpa] Could not refresh catalog "
+                f"({err}); using disk cache.[/yellow]"
+            )
+            data = disk
+        else:
+            fixture = _read_fixture()
+            if fixture.get("templates"):
                 console.print(
                     "[yellow][cpa] Could not refresh catalog "
-                    f"({err}); using disk cache.[/yellow]"
+                    f"({err}); using fixture.[/yellow]"
                 )
-                data = disk
+                data = fixture
             else:
-                fixture = _read_fixture()
-                if fixture.get("templates"):
-                    console.print(
-                        "[yellow][cpa] Could not refresh catalog "
-                        f"({err}); using fixture.[/yellow]"
-                    )
-                    data = fixture
-                else:
-                    raise RuntimeError(
-                        f"Failed to load template catalog: {err}"
-                    ) from err
+                raise RuntimeError(f"Failed to load template catalog: {err}") from err
 
     _memory_cache = data
     _memory_ts = time.time()
@@ -471,44 +574,96 @@ def reset_catalog_cache_for_tests() -> None:
 
 def list_templates() -> None:
     data = get_catalog_data()
-    table = Table(title="Templates")
-    table.add_column("slug")
-    table.add_column("category")
-    table.add_column("type")
-    for t in data.get("templates", []):
-        table.add_row(
-            str(t.get("slug", "")),
-            str(t.get("category", "")),
-            str(t.get("type", "")),
-        )
-    console.print(table)
+    categories = category_index(data)
+    templates = [t for t in data.get("templates", []) if isinstance(t, dict)]
+
+    console.print("[bold blue]\nAvailable Templates:[/bold blue]")
+    # Preserve catalog category order, then any unknown slugs.
+    ordered_slugs = list(categories)
+    seen: set[str] = set()
+    for slug in ordered_slugs:
+        seen.add(slug)
+        group = [t for t in templates if str(t.get("category", "")) == slug]
+        if not group:
+            continue
+        info = categories[slug]
+        console.print(f"[bold green]\n{info.name}:[/bold green]")
+        if info.description:
+            console.print(f"  {info.description}")
+        if info.details:
+            console.print(f"  [dim]{info.details}[/dim]")
+        if info.labels:
+            console.print(f"  [dim]Keywords: {', '.join(info.labels)}[/dim]")
+        for template in group:
+            name = str(template.get("name", template.get("slug", "")))
+            tslug = str(template.get("slug", ""))
+            console.print(f"  [yellow]{name}[/yellow] ([cyan]{tslug}[/cyan])")
+            desc = str(template.get("description", "")).strip()
+            if desc:
+                console.print(f"    {desc}")
+            labels = template.get("labels", [])
+            if isinstance(labels, list) and labels:
+                console.print(f"    Keywords: {', '.join(str(x) for x in labels)}")
+
+    orphans = [t for t in templates if str(t.get("category", "")) not in seen]
+    if orphans:
+        console.print("[bold green]\nOther:[/bold green]")
+        for template in orphans:
+            name = str(template.get("name", template.get("slug", "")))
+            tslug = str(template.get("slug", ""))
+            console.print(f"  [yellow]{name}[/yellow] ([cyan]{tslug}[/cyan])")
 
 
 def list_addons(template_slug: str | None = None) -> None:
     data = get_catalog_data()
+    categories = category_index(data)
     template_type: str | None = None
     if template_slug:
         for t in data.get("templates", []):
-            if t.get("slug") == template_slug:
+            if isinstance(t, dict) and t.get("slug") == template_slug:
                 template_type = str(t.get("type", ""))
                 break
 
-    table = Table(title="Extensions")
-    table.add_column("slug")
-    table.add_column("category")
-    table.add_column("type")
-    for ext in data.get("extensions", data.get("addons", [])):
+    console.print("[bold blue]\nAvailable Addons:[/bold blue]")
+    if template_slug:
+        console.print(
+            f"[bold green]\nCompatible with template: {template_slug}[/bold green]"
+        )
+
+    extensions = [
+        ext
+        for ext in data.get("extensions", data.get("addons", []))
+        if isinstance(ext, dict)
+    ]
+    grouped: dict[str, list[dict[str, Any]]] = {}
+    for ext in extensions:
         ext_types = ext.get("type", [])
         if isinstance(ext_types, str):
             ext_types = [ext_types]
         if template_type and template_type not in ext_types:
             continue
-        type_label = (
-            ", ".join(ext_types) if isinstance(ext_types, list) else str(ext_types)
-        )
-        table.add_row(
-            str(ext.get("slug", "")),
-            str(ext.get("category", "")),
-            type_label,
-        )
-    console.print(table)
+        slug = str(ext.get("category", "custom"))
+        grouped.setdefault(slug, []).append(ext)
+
+    for slug in list(categories) + [s for s in grouped if s not in categories]:
+        group = grouped.get(slug)
+        if not group:
+            continue
+        info = categories.get(slug) or CategoryInfo(slug=slug, name=slug)
+        console.print(f"[bold green]\n{info.name}:[/bold green]")
+        if info.description:
+            console.print(f"  {info.description}")
+        if info.details:
+            console.print(f"  [dim]{info.details}[/dim]")
+        if info.labels:
+            console.print(f"  [dim]Keywords: {', '.join(info.labels)}[/dim]")
+        for ext in group:
+            name = str(ext.get("name", ext.get("slug", "")))
+            eslug = str(ext.get("slug", ""))
+            console.print(f"  [yellow]{name}[/yellow] ([cyan]{eslug}[/cyan])")
+            desc = str(ext.get("description", "")).strip()
+            if desc:
+                console.print(f"    {desc}")
+            labels = ext.get("labels", [])
+            if isinstance(labels, list) and labels:
+                console.print(f"    Keywords: {', '.join(str(x) for x in labels)}")

{create_awesome_python_app-0.2.6 → create_awesome_python_app-0.2.7}/src/create_awesome_python_app/cli.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import asyncio
 import os
+import sys
 from pathlib import Path
 from typing import Any
 
@@ -25,17 +26,60 @@ from rich.console import Console
 
 from create_awesome_python_app import __version__
 
+# Sentinel for bare ``--fixture`` (optional DIR rewritten in argv preprocess).
+_FIXTURE_AUTO = "__CPA_FIXTURE_AUTO__"
+
 app = typer.Typer(
     name="create-awesome-python-app",
     help="Composable scaffolding CLI for production-ready Python apps.",
     no_args_is_help=False,
     add_completion=True,
+    # Keep cache out of this Typer app (routed in main()). A nested command
+    # group turns the CLI into Click Group form `[ARGS] COMMAND`, so
+    # `cpa my-api --template …` fails with "No such command '--template'".
+    epilog="Cache: create-awesome-python-app cache [list|dir|clean|verify|…]",
 )
 cache_app = typer.Typer(help="Inspect and manage the local template cache")
-app.add_typer(cache_app, name="cache")
 console = Console(stderr=True)
 
 
+def _preprocess_fixture_argv(argv: list[str] | None = None) -> list[str]:
+    """Rewrite bare ``--fixture`` to ``--fixture=__CPA_FIXTURE_AUTO__``.
+
+    Typer/Click requires an option argument; Commander allows ``--fixture [dir]``.
+    This keeps CNA-compatible UX: ``--fixture`` alone enables auto-detect mode.
+    """
+    raw = list(sys.argv if argv is None else argv)
+    if not raw:
+        return raw
+    out = [raw[0]]
+    i = 1
+    while i < len(raw):
+        arg = raw[i]
+        if arg == "--fixture":
+            if i + 1 < len(raw) and not raw[i + 1].startswith("-"):
+                out.extend(["--fixture", raw[i + 1]])
+                i += 2
+            else:
+                out.append(f"--fixture={_FIXTURE_AUTO}")
+                i += 1
+            continue
+        out.append(arg)
+        i += 1
+    if argv is None:
+        sys.argv = out
+    return out
+
+
+def apply_fixture_mode(fixture: str | None) -> None:
+    """Translate ``--fixture`` into ``CPA_CATALOG_FIXTURE`` / ``CPA_FIXTURE_DIR``."""
+    if fixture is None and os.environ.get("CPA_CATALOG_FIXTURE") != "1":
+        return
+    os.environ["CPA_CATALOG_FIXTURE"] = "1"
+    if fixture is not None and fixture != _FIXTURE_AUTO and fixture != "":
+        os.environ["CPA_FIXTURE_DIR"] = fixture
+
+
 def _in_ci() -> bool:
     return os.environ.get("CI", "").lower() in {"1", "true", "yes"}
 
@@ -159,9 +203,8 @@ def main() -> None:
     `create-awesome-python-app cache dir` works (Typer would otherwise
     treat `cache` as project_directory).
     """
-    import sys
-
     check_python_version(">=3.12", "create-awesome-python-app")
+    _preprocess_fixture_argv()
     if len(sys.argv) > 1 and sys.argv[1] == "cache":
         sys.argv = [sys.argv[0], *sys.argv[2:]]
         cache_app(prog_name="create-awesome-python-app cache")
@@ -169,9 +212,8 @@ def main() -> None:
     app()
 
 
-@app.callback(invoke_without_command=True)
+@app.command(name="create-awesome-python-app")
 def scaffold(
-    ctx: typer.Context,
     project_directory: str | None = typer.Argument("my-project"),
     version: bool = typer.Option(False, "--version"),
     info: bool = typer.Option(False, "--info", "-i"),
@@ -192,14 +234,25 @@ def scaffold(
     refresh: str | None = typer.Option(None, "--refresh"),
     strict_version: bool = typer.Option(False, "--strict-version"),
     keep_on_failure: bool = typer.Option(False, "--keep-on-failure"),
+    fixture: str | None = typer.Option(
+        None,
+        "--fixture",
+        help=(
+            "Load the template catalog from the local fixtures/ directory "
+            "instead of the network (optional DIR = repo root; also "
+            "CPA_FIXTURE_DIR / CPA_CATALOG_FIXTURE)"
+        ),
+    ),
 ) -> None:
     if version:
         console.print(__version__)
         raise typer.Exit(0)
     if info:
         print_env_info()
-    if ctx.invoked_subcommand is not None:
-        return
+
+    # Translate --fixture into env vars before catalog loads
+    # (--list-templates / interactive / scaffold).
+    apply_fixture_mode(fixture)
 
     if list_templates or list_addons:
         from create_awesome_python_app.catalog import list_addons as la
@@ -315,12 +368,22 @@ def scaffold(
             extension_choices = build_extension_choices(interactive_catalog, template)
             grouped_extensions = group_extension_choices(extension_choices)
             if grouped_extensions:
+                from create_awesome_python_app.catalog import (
+                    CategoryInfo,
+                    category_index,
+                    format_category_choice_title,
+                )
+
+                categories = category_index(interactive_catalog)
                 category_choices = [
                     Choice(
-                        title=(
-                            f"{choices[0].category_name} "
-                            f"({len(choices)} extension"
-                            f"{'s' if len(choices) != 1 else ''})"
+                        title=format_category_choice_title(
+                            categories.get(category_slug)
+                            or CategoryInfo(
+                                slug=category_slug,
+                                name=choices[0].category_name,
+                            ),
+                            len(choices),
                         ),
                         value=category_slug,
                     )
@@ -444,8 +507,29 @@ def cache_dir_cmd() -> None:
     console.print(str(default_cache_dir()))
 
 
+def _cache_json_print(payload: Any) -> None:
+    """Print machine-readable JSON to stdout (not the stderr console)."""
+    import json
+    from dataclasses import asdict, is_dataclass
+
+    def _to_jsonable(value: Any) -> Any:
+        if isinstance(value, Path):
+            return str(value)
+        if is_dataclass(value) and not isinstance(value, type):
+            return {k: _to_jsonable(v) for k, v in asdict(value).items()}
+        if isinstance(value, list):
+            return [_to_jsonable(item) for item in value]
+        if isinstance(value, dict):
+            return {k: _to_jsonable(v) for k, v in value.items()}
+        return value
+
+    typer.echo(json.dumps(_to_jsonable(payload), indent=2))
+
+
 @cache_app.command("list")
-def cache_list_cmd() -> None:
+def cache_list_cmd(
+    json_out: bool = typer.Option(False, "--json", help="Output as JSON"),
+) -> None:
     from create_awesome_python_app.cache import (
         format_age,
         format_bytes,
@@ -454,6 +538,9 @@ def cache_list_cmd() -> None:
     )
 
     entries = list_cache_entries()
+    if json_out:
+        _cache_json_print(entries)
+        return
     if not entries:
         console.print("[dim]No cached templates or extensions.[/dim]")
         console.print(
@@ -488,10 +575,38 @@ def cache_list_cmd() -> None:
 def cache_clean_cmd(
     id: str | None = typer.Argument(None),
     catalog: bool = typer.Option(False, "--catalog"),
+    json_out: bool = typer.Option(False, "--json", help="Output as JSON"),
+    force: bool = typer.Option(
+        False, "--force", "-f", help="Skip interactive confirmation"
+    ),
 ) -> None:
     from create_awesome_python_app.cache import clean_cache
 
+    # Targeted cleans (id / --catalog) never prompt.
+    if not catalog and id is None and not json_out and not force:
+        if not sys.stdin.isatty():
+            console.print(
+                "[yellow]Non-interactive shell — use --json or --force to skip "
+                "the prompt, or specify an id to target a specific entry.[/yellow]"
+            )
+            return
+        import questionary
+
+        from create_awesome_python_app.prompt_style import CPA_PROMPT_STYLE
+
+        confirmed = questionary.confirm(
+            "Remove ALL cached templates and extensions?",
+            default=False,
+            style=CPA_PROMPT_STYLE,
+        ).ask()
+        if not confirmed:
+            console.print("[dim]Clean cancelled.[/dim]")
+            return
+
     result = clean_cache(id, catalog=catalog)
+    if json_out:
+        _cache_json_print(result)
+        return
     if result.not_found:
         console.print(f"[yellow]No cache entry found for id: {id}[/yellow]")
         return
@@ -503,10 +618,18 @@ def cache_clean_cmd(
 
 
 @cache_app.command("verify")
-def cache_verify_cmd(id: str | None = typer.Argument(None)) -> None:
+def cache_verify_cmd(
+    id: str | None = typer.Argument(None),
+    json_out: bool = typer.Option(False, "--json", help="Output as JSON"),
+) -> None:
     from create_awesome_python_app.cache import verify_cache
 
     results = verify_cache(id)
+    if json_out:
+        _cache_json_print(results)
+        if any(not bool(entry.fsck_ok) for entry in results):
+            raise typer.Exit(1)
+        raise typer.Exit(0)
     if not results:
         console.print("[dim]No cached entries.[/dim]")
         raise typer.Exit(0)
@@ -527,10 +650,15 @@ def cache_verify_cmd(id: str | None = typer.Argument(None)) -> None:
 
 
 @cache_app.command("outdated")
-def cache_outdated_cmd() -> None:
+def cache_outdated_cmd(
+    json_out: bool = typer.Option(False, "--json", help="Output as JSON"),
+) -> None:
     from create_awesome_python_app.cache import check_outdated
 
     results = check_outdated()
+    if json_out:
+        _cache_json_print(results)
+        return
     if not results:
         console.print("[dim]No cached entries to check.[/dim]")
         return
@@ -590,10 +718,17 @@ def cache_update_cmd(id: str | None = typer.Argument(None)) -> None:
 
 
 @cache_app.command("doctor")
-def cache_doctor_cmd() -> None:
+def cache_doctor_cmd(
+    json_out: bool = typer.Option(False, "--json", help="Output as JSON"),
+) -> None:
     from create_awesome_python_app.cache import run_doctor
 
     results = run_doctor()
+    if json_out:
+        _cache_json_print(results)
+        if any(not row.ok for row in results):
+            raise typer.Exit(1)
+        raise typer.Exit(0)
     all_ok = True
     for row in results:
         mark = "[green]✓[/green]" if row.ok else "[red]✗[/red]"

create_awesome_python_app-0.2.7/tests/conftest.py

@@ -0,0 +1,39 @@
+"""Shared test fixtures for create-awesome-python-app."""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+_CPA_ENV_VARS = (
+    "CPA_REFRESH",
+    "CPA_NO_CATALOG_CACHE",
+    "CPA_CACHE_DIR",
+    "CPA_CATALOG_FIXTURE",
+    "CPA_FIXTURE_DIR",
+)
+
+
+@pytest.fixture(autouse=True)
+def _clean_cpa_process_env():
+    """Clear CPA env vars that CLI helpers set via ``os.environ`` (not monkeypatch).
+
+    ``apply_fixture_mode`` mutates ``os.environ`` directly. Pairing that with
+    ``monkeypatch.delenv`` after the test can restore the leaked value when
+    monkeypatch undoes its stack — so cleanup must use ``os.environ.pop``.
+    """
+    from create_awesome_python_app.catalog import (
+        reset_catalog_cache_for_tests,
+        reset_fixture_root_for_tests,
+    )
+
+    for name in _CPA_ENV_VARS:
+        os.environ.pop(name, None)
+    reset_catalog_cache_for_tests()
+    reset_fixture_root_for_tests()
+    yield
+    for name in _CPA_ENV_VARS:
+        os.environ.pop(name, None)
+    reset_catalog_cache_for_tests()
+    reset_fixture_root_for_tests()

{create_awesome_python_app-0.2.6 → create_awesome_python_app-0.2.7}/tests/test_cache_cmds.py

@@ -198,3 +198,72 @@ def test_list_cli_shows_table(cache_root: Path) -> None:
     text = _out(result)
     assert "demo" in text
     assert "SHA" in text
+
+
+def test_cache_list_verify_doctor_json(
+    cache_root: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    import json
+
+    entry = cache_root / "repos" / "demo"
+    sha = _init_git_repo(entry)
+    write_cache_meta(
+        entry,
+        CacheMeta(
+            url="https://example.com/repo.git",
+            ref="main",
+            fetched_at=time.time(),
+            commit=sha,
+        ),
+    )
+    monkeypatch.setattr(
+        "create_awesome_python_app.cache._probe_network",
+        lambda: __import__(
+            "create_awesome_python_app.cache", fromlist=["DoctorResult"]
+        ).DoctorResult(check="network", ok=True, detail="mocked"),
+    )
+
+    listed = runner.invoke(cache_app, ["list", "--json"])
+    assert listed.exit_code == 0, _out(listed)
+    payload = json.loads(listed.stdout)
+    assert payload[0]["id"] == "demo"
+    assert payload[0]["commit"] == sha
+
+    verified = runner.invoke(cache_app, ["verify", "--json"])
+    assert verified.exit_code == 0, _out(verified)
+    assert json.loads(verified.stdout)[0]["fsck_ok"] is True
+
+    doctor = runner.invoke(cache_app, ["doctor", "--json"])
+    assert doctor.exit_code == 0, _out(doctor)
+    assert any(row["check"] == "git" for row in json.loads(doctor.stdout))
+
+    outdated = runner.invoke(cache_app, ["outdated", "--json"])
+    assert outdated.exit_code == 0, _out(outdated)
+    assert isinstance(json.loads(outdated.stdout), list)
+
+
+def test_cache_clean_json_and_force(cache_root: Path) -> None:
+    import json
+
+    entry = cache_root / "repos" / "demo"
+    _init_git_repo(entry)
+
+    blocked = runner.invoke(cache_app, ["clean"])
+    assert blocked.exit_code == 0
+    assert "Non-interactive" in _out(blocked)
+    assert entry.exists()
+
+    forced = runner.invoke(cache_app, ["clean", "--json"])
+    assert forced.exit_code == 0, _out(forced)
+    payload = json.loads(forced.stdout)
+    assert str(entry) in payload["removed"]
+    assert not entry.exists()
+
+
+def test_cache_clean_force_without_json(cache_root: Path) -> None:
+    entry = cache_root / "repos" / "demo"
+    _init_git_repo(entry)
+    result = runner.invoke(cache_app, ["clean", "--force"])
+    assert result.exit_code == 0, _out(result)
+    assert "Removed" in _out(result)
+    assert not entry.exists()

create_awesome_python_app-0.2.7/tests/test_catalog.py

@@ -0,0 +1,21 @@
+from create_awesome_python_app.cli import app
+from typer.testing import CliRunner
+
+runner = CliRunner()
+
+
+def _out(result) -> str:
+    return (result.stdout or "") + (result.stderr or "")
+
+
+def test_list_templates() -> None:
+    result = runner.invoke(app, ["--list-templates"])
+    assert result.exit_code == 0
+    text = _out(result)
+    assert "Available Templates" in text
+
+
+def test_list_addons() -> None:
+    result = runner.invoke(app, ["--list-addons"])
+    assert result.exit_code == 0
+    assert "Available Addons" in _out(result)

{create_awesome_python_app-0.2.6 → create_awesome_python_app-0.2.7}/tests/test_catalog_fetch.py

@@ -13,6 +13,9 @@ from create_awesome_python_app.catalog import (
     catalog_url,
     get_catalog_data,
     reset_catalog_cache_for_tests,
+    reset_fixture_root_for_tests,
+    resolve_fixture_root,
+    set_fixture_root_for_tests,
 )
 
 FIXTURE_PATH = (
@@ -21,9 +24,15 @@ FIXTURE_PATH = (
 
 
 @pytest.fixture(autouse=True)
-def _reset_cache(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+def _reset_cache(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
     reset_catalog_cache_for_tests()
+    reset_fixture_root_for_tests()
     monkeypatch.setenv("CPA_CACHE_DIR", str(tmp_path / "cache"))
+    monkeypatch.delenv("CPA_FIXTURE_DIR", raising=False)
+    monkeypatch.delenv("CPA_CATALOG_FIXTURE", raising=False)
+    yield
+    reset_fixture_root_for_tests()
+    reset_catalog_cache_for_tests()
 
 
 def test_default_catalog_url(monkeypatch: pytest.MonkeyPatch) -> None:
@@ -83,3 +92,33 @@ def test_get_catalog_data_disk_fallback_on_network_error(
 
 def test_default_url_points_to_cpa_templates() -> None:
     assert DEFAULT_CATALOG_URL.endswith("/cpa-templates/main/templates.json")
+
+
+def test_resolve_fixture_root_respects_env(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv("CPA_FIXTURE_DIR", str(tmp_path))
+    assert resolve_fixture_root() == tmp_path.resolve()
+
+
+def test_get_catalog_data_fixture_uses_custom_dir(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    catalog_dir = tmp_path / "fixtures" / "catalog"
+    catalog_dir.mkdir(parents=True)
+    payload = {
+        "templates": [{"slug": "from-env-fixture"}],
+        "extensions": [],
+        "categories": [],
+    }
+    (catalog_dir / "templates.json").write_text(json.dumps(payload), encoding="utf-8")
+    monkeypatch.setenv("CPA_CATALOG_FIXTURE", "1")
+    monkeypatch.setenv("CPA_FIXTURE_DIR", str(tmp_path))
+    data = get_catalog_data(force_refresh=True)
+    assert data["templates"][0]["slug"] == "from-env-fixture"
+
+
+def test_set_fixture_root_for_tests(tmp_path: Path) -> None:
+    set_fixture_root_for_tests(tmp_path)
+    assert resolve_fixture_root() == tmp_path
+    reset_fixture_root_for_tests()

{create_awesome_python_app-0.2.6 → create_awesome_python_app-0.2.7}/tests/test_catalog_resolve.py

@@ -307,3 +307,32 @@ def test_find_incompatible_pairs_dedupes_symmetric_edges() -> None:
     }
     pairs = find_incompatible_pairs(["a", "b"], catalog=catalog)
     assert pairs == [("a", "b")]
+
+
+def test_category_index_includes_rich_metadata() -> None:
+    from create_awesome_python_app.catalog import (
+        category_index,
+        format_category_choice_title,
+    )
+
+    catalog = {
+        "categories": [
+            {
+                "slug": "backend-applications",
+                "name": "Backend Applications",
+                "description": "API starters",
+                "details": "FastAPI and friends",
+                "labels": ["Backend", "API"],
+            }
+        ],
+        "templates": [],
+        "extensions": [],
+    }
+    info = category_index(catalog)["backend-applications"]
+    assert info.description == "API starters"
+    assert info.details == "FastAPI and friends"
+    assert info.labels == ("Backend", "API")
+    title = format_category_choice_title(info, 2)
+    assert "Backend Applications (2 extensions)" in title
+    assert "API starters" in title
+    assert "Backend" in title

{create_awesome_python_app-0.2.6 → create_awesome_python_app-0.2.7}/tests/test_cli.py

@@ -1,3 +1,4 @@
+import os
 from pathlib import Path
 
 import pytest
@@ -6,16 +7,6 @@ from create_awesome_python_app.cli import app
 from typer.testing import CliRunner
 
 runner = CliRunner()
-_CPA_ENV_VARS = ("CPA_REFRESH", "CPA_NO_CATALOG_CACHE", "CPA_CACHE_DIR")
-
-
-@pytest.fixture(autouse=True)
-def _clean_cpa_env(monkeypatch):
-    for name in _CPA_ENV_VARS:
-        monkeypatch.delenv(name, raising=False)
-    yield
-    for name in _CPA_ENV_VARS:
-        monkeypatch.delenv(name, raising=False)
 
 
 def test_version() -> None:
@@ -223,3 +214,124 @@ def test_incompatible_addons_fail_fast(tmp_path: Path, monkeypatch) -> None:
     assert result.exit_code == 2
     assert "Incompatible extension combination" in text
     assert "saga" in text
+
+
+def test_help_mentions_fixture() -> None:
+    result = runner.invoke(app, ["--help"])
+    assert result.exit_code == 0
+    text = (result.stdout or "") + (result.stderr or "")
+    assert "fixture" in text.lower()
+
+
+def test_options_after_project_directory(tmp_path: Path, monkeypatch) -> None:
+    """Regression: README-style `cpa my-api --template …` must work.
+
+    Registering a Typer subcommand group made Click treat ``--template`` as a
+    COMMAND after the positional project directory.
+    """
+    tpl = tmp_path / "tpl"
+    tpl.mkdir()
+    captured: dict[str, object] = {}
+
+    async def fake_check_for_latest_version(_package_name):
+        return None
+
+    async def fake_create_python_app(project_directory, options, *_args, **_kwargs):
+        captured["project_directory"] = project_directory
+        captured["options"] = options
+
+    monkeypatch.setattr(
+        "create_awesome_python_app.cli.check_for_latest_version",
+        fake_check_for_latest_version,
+    )
+    monkeypatch.setattr(
+        "create_awesome_python_app.cli.create_python_app",
+        fake_create_python_app,
+    )
+
+    result = runner.invoke(
+        app,
+        [
+            "my-api",
+            "--template",
+            f"file://{tpl}",
+            "--addons",
+            "github-setup",
+            "--no-install",
+            "--no-interactive",
+        ],
+    )
+
+    text = (result.stdout or "") + (result.stderr or "")
+    assert result.exit_code == 0, text
+    assert "No such command" not in text
+    assert captured["project_directory"] == "my-api"
+    options = captured["options"]
+    assert isinstance(options, dict)
+    assert options["template"] == f"file://{tpl}"
+
+
+def test_preprocess_fixture_argv_bare_and_with_dir() -> None:
+    from create_awesome_python_app.cli import _FIXTURE_AUTO, _preprocess_fixture_argv
+
+    assert _preprocess_fixture_argv(["cpa", "--fixture", "--list-templates"]) == [
+        "cpa",
+        f"--fixture={_FIXTURE_AUTO}",
+        "--list-templates",
+    ]
+    assert _preprocess_fixture_argv(
+        ["cpa", "--fixture", "./my-fixtures", "--list-templates"]
+    ) == ["cpa", "--fixture", "./my-fixtures", "--list-templates"]
+
+
+def test_fixture_flag_enables_catalog_fixture(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    from create_awesome_python_app.cli import _FIXTURE_AUTO, apply_fixture_mode
+
+    apply_fixture_mode(_FIXTURE_AUTO)
+    assert os.environ.get("CPA_CATALOG_FIXTURE") == "1"
+    assert "CPA_FIXTURE_DIR" not in os.environ
+
+    monkeypatch.delenv("CPA_CATALOG_FIXTURE", raising=False)
+    monkeypatch.delenv("CPA_FIXTURE_DIR", raising=False)
+    apply_fixture_mode(str(tmp_path))
+    assert os.environ.get("CPA_CATALOG_FIXTURE") == "1"
+    assert os.environ.get("CPA_FIXTURE_DIR") == str(tmp_path)
+
+
+def test_list_templates_with_fixture_dir(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    import json
+    import os
+
+    catalog_dir = tmp_path / "fixtures" / "catalog"
+    catalog_dir.mkdir(parents=True)
+    (catalog_dir / "templates.json").write_text(
+        json.dumps(
+            {
+                "templates": [
+                    {
+                        "slug": "fixture-only",
+                        "category": "tooling",
+                        "type": "cli",
+                    }
+                ],
+                "extensions": [],
+                "categories": [],
+            }
+        ),
+        encoding="utf-8",
+    )
+    monkeypatch.delenv("CPA_CATALOG_FIXTURE", raising=False)
+    monkeypatch.delenv("CPA_FIXTURE_DIR", raising=False)
+
+    result = runner.invoke(
+        app,
+        ["--fixture", str(tmp_path), "--list-templates"],
+    )
+    text = (result.stdout or "") + (result.stderr or "")
+    assert result.exit_code == 0, text
+    assert "fixture-only" in text
+    assert os.environ.get("CPA_CATALOG_FIXTURE") == "1"

{create_awesome_python_app-0.2.6 → create_awesome_python_app-0.2.7}/tests/test_cpa_templates_integration.py

@@ -21,6 +21,19 @@ def _cpa_templates_available() -> bool:
     return (FASTAPI_TEMPLATE / "pyproject.toml").is_file()
 
 
+def _clean_fixture_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Ensure subprocess scaffolds are not forced into fixture mode."""
+    monkeypatch.delenv("CPA_CATALOG_FIXTURE", raising=False)
+    monkeypatch.delenv("CPA_FIXTURE_DIR", raising=False)
+
+
+def _subprocess_env() -> dict[str, str]:
+    env = os.environ.copy()
+    env.pop("CPA_CATALOG_FIXTURE", None)
+    env.pop("CPA_FIXTURE_DIR", None)
+    return env
+
+
 @pytest.mark.skipif(
     not _cpa_templates_available(),
     reason="cpa-templates checkout not available (set CPA_TEMPLATES_ROOT)",
@@ -28,6 +41,7 @@ def _cpa_templates_available() -> bool:
 def test_scaffold_fastapi_starter_from_cpa_templates(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
+    _clean_fixture_env(monkeypatch)
     monkeypatch.setenv("CI", "1")
     monkeypatch.setenv("CPA_SKIP_GIT", "1")
     monkeypatch.setenv("CPA_CACHE_DIR", str(tmp_path / "cpa-cache"))
@@ -48,6 +62,7 @@ def test_scaffold_fastapi_starter_from_cpa_templates(
         cwd=_REPO_ROOT,
         capture_output=True,
         text=True,
+        env=_subprocess_env(),
         check=False,
     )
     assert result.returncode == 0, result.stdout + result.stderr
@@ -78,6 +93,7 @@ def test_scaffold_fastapi_starter_via_catalog_slug(
     """Scaffold using --template fastapi-starter slug (issue #160 / #161)."""
     import json
 
+    _clean_fixture_env(monkeypatch)
     monkeypatch.setenv("CI", "1")
     monkeypatch.setenv("CPA_SKIP_GIT", "1")
     monkeypatch.setenv("CPA_CACHE_DIR", str(tmp_path / "cpa-cache"))
@@ -114,6 +130,7 @@ def test_scaffold_fastapi_starter_via_catalog_slug(
         cwd=_REPO_ROOT,
         capture_output=True,
         text=True,
+        env=_subprocess_env(),
         check=False,
     )
     assert result.returncode == 0, result.stdout + result.stderr
@@ -129,6 +146,7 @@ def test_scaffold_via_catalog_addon_slug(
 ) -> None:
     import json
 
+    _clean_fixture_env(monkeypatch)
     monkeypatch.setenv("CI", "1")
     monkeypatch.setenv("CPA_SKIP_GIT", "1")
     monkeypatch.setenv("CPA_CACHE_DIR", str(tmp_path / "cpa-cache"))
@@ -170,6 +188,7 @@ def test_scaffold_via_catalog_addon_slug(
         cwd=_REPO_ROOT,
         capture_output=True,
         text=True,
+        env=_subprocess_env(),
         check=False,
     )
     assert result.returncode == 0, result.stdout + result.stderr
@@ -183,6 +202,7 @@ def test_scaffold_via_catalog_addon_slug(
 def test_scaffold_fastapi_with_github_setup_extension(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
+    _clean_fixture_env(monkeypatch)
     monkeypatch.setenv("CI", "1")
     monkeypatch.setenv("CPA_SKIP_GIT", "1")
     monkeypatch.setenv("CPA_CACHE_DIR", str(tmp_path / "cpa-cache"))
@@ -204,6 +224,7 @@ def test_scaffold_fastapi_with_github_setup_extension(
         cwd=_REPO_ROOT,
         capture_output=True,
         text=True,
+        env=_subprocess_env(),
         check=False,
     )
     assert result.returncode == 0, result.stdout + result.stderr

create_awesome_python_app-0.2.6/tests/test_catalog.py

@@ -1,13 +0,0 @@
-from create_awesome_python_app.cli import app
-from typer.testing import CliRunner
-
-runner = CliRunner()
-
-
-def test_list_templates() -> None:
-    result = runner.invoke(app, ["--list-templates"])
-    assert result.exit_code == 0
-
-
-def test_list_addons() -> None:
-    assert runner.invoke(app, ["--list-addons"]).exit_code == 0