codefortify-starter 1.0.0__py3-none-any.whl

codefortify_starter/__init__.py

@@ -0,0 +1,7 @@
+"""Codefortify starter project generator package."""
+
+from codefortify_starter.constants import PACKAGE_VERSION
+
+__all__ = ["PACKAGE_VERSION", "__version__"]
+
+__version__ = PACKAGE_VERSION

codefortify_starter/__main__.py

@@ -0,0 +1,6 @@
+from codefortify_starter.cli import main
+
+
+if __name__ == "__main__":
+    main()
+

codefortify_starter/cli.py

@@ -0,0 +1,103 @@
+"""CLI entry point for project generation."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from codefortify_starter.generator import StarterProjectGenerator, build_generation_options
+from codefortify_starter.validators import ValidationError, build_project_identity, normalize_database
+
+
+console = Console()
+
+
+def run(
+    project_name: str = typer.Argument(..., help="Project directory name to create."),
+    htmx: bool = typer.Option(False, "--htmx", help="Include HTMX integration."),
+    drf: bool = typer.Option(False, "--drf", help="Include Django REST Framework starter API."),
+    docker: bool = typer.Option(False, "--docker", help="Include Docker and Compose files."),
+    celery: bool = typer.Option(False, "--celery", help="Include Celery + Redis task setup."),
+    database: str | None = typer.Option(
+        None,
+        "--database",
+        help="Database backend to configure: sqlite, postgres, or mysql.",
+    ),
+    no_git: bool = typer.Option(False, "--no-git", help="Skip git repository initialization."),
+    force: bool = typer.Option(False, "--force", help="Allow generation into an existing directory."),
+    directory: Path = typer.Option(Path("."), "--directory", help="Parent directory for the generated project."),
+    all_features: bool = typer.Option(
+        False,
+        "--all",
+        help="Enable full-stack preset: --htmx --drf --docker --celery --database postgres.",
+    ),
+) -> None:
+    """Generate a Django starter project."""
+    try:
+        if all_features:
+            htmx = True
+            drf = True
+            docker = True
+            celery = True
+            if database is None:
+                database = "postgres"
+
+        resolved_database = normalize_database(database, use_docker=docker)
+        identity = build_project_identity(project_name)
+
+        options = build_generation_options(
+            project_name=identity.project_name,
+            project_slug=identity.project_slug,
+            project_title=identity.project_title,
+            project_package=identity.project_package,
+            project_class_name=identity.project_class_name,
+            directory=directory.resolve(),
+            database=resolved_database,
+            use_htmx=htmx,
+            use_drf=drf,
+            use_docker=docker,
+            use_celery=celery,
+            no_git=no_git,
+            force=force,
+        )
+        generator = StarterProjectGenerator()
+        result = generator.generate(options)
+    except (ValidationError, FileExistsError, NotADirectoryError, RuntimeError) as exc:
+        console.print(f"[bold red]Error:[/bold red] {exc}")
+        raise typer.Exit(code=1) from exc
+
+    selected_features = []
+    if htmx:
+        selected_features.append("htmx")
+    if drf:
+        selected_features.append("drf")
+    if docker:
+        selected_features.append("docker")
+    if celery:
+        selected_features.append("celery")
+    features_text = ", ".join(selected_features) if selected_features else "base"
+
+    console.print(
+        f"[bold green]Created[/bold green] {result.project_path} "
+        f"(database={resolved_database}, features={features_text})"
+    )
+    if result.warnings:
+        for warning in result.warnings:
+            console.print(f"[yellow]Warning:[/yellow] {warning}")
+
+    console.print("Next steps:")
+    console.print(f"  1. cd {result.project_path}")
+    console.print("  2. python -m venv .venv && source .venv/bin/activate")
+    console.print("  3. pip install -r requirements.txt")
+    console.print("  4. cp .env.example .env")
+    console.print("  5. python manage.py migrate && python manage.py runserver")
+
+
+def main() -> None:
+    typer.run(run)
+
+
+if __name__ == "__main__":
+    main()

codefortify_starter/constants.py

@@ -0,0 +1,48 @@
+"""Shared constants for the starter generator."""
+
+from __future__ import annotations
+
+from typing import Final
+
+
+PACKAGE_NAME: Final[str] = "codefortify-starter"
+IMPORT_PACKAGE: Final[str] = "codefortify_starter"
+CLI_COMMAND: Final[str] = "codefortify-startproject"
+PACKAGE_VERSION: Final[str] = "1.0.0"
+
+VALID_DATABASES: Final[tuple[str, ...]] = ("sqlite", "postgres", "mysql")
+
+BASE_REQUIREMENTS: Final[tuple[str, ...]] = (
+    "Django>=5.2,<5.3",
+    "python-decouple>=3.8,<4.0",
+)
+
+FEATURE_REQUIREMENTS: Final[dict[str, tuple[str, ...]]] = {
+    "htmx": ("django-htmx>=1.20.0,<2.0",),
+    "drf": (
+        "djangorestframework>=3.15.0,<4.0",
+        "django-filter>=24.0,<26.0",
+    ),
+    "docker": (
+        "gunicorn>=23.0.0,<24.0",
+        "whitenoise>=6.8.0,<7.0",
+    ),
+    "celery": (
+        "celery>=5.4.0,<6.0",
+        "redis>=5.0.0,<6.0",
+    ),
+}
+
+DATABASE_REQUIREMENTS: Final[dict[str, tuple[str, ...]]] = {
+    "sqlite": (),
+    "postgres": (
+        "dj-database-url>=2.3.0,<3.0",
+        "psycopg2-binary>=2.9.9,<3.0",
+    ),
+    "mysql": (
+        "dj-database-url>=2.3.0,<3.0",
+        "PyMySQL>=1.1.0,<2.0",
+    ),
+}
+
+EXECUTABLE_FILES: Final[tuple[str, ...]] = ("entrypoint.sh", "docker_deploy.sh")

codefortify_starter/generator.py

@@ -0,0 +1,246 @@
+"""Project generation orchestration."""
+
+from __future__ import annotations
+
+import os
+import re
+import stat
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from codefortify_starter.constants import (
+    BASE_REQUIREMENTS,
+    DATABASE_REQUIREMENTS,
+    EXECUTABLE_FILES,
+    FEATURE_REQUIREMENTS,
+    PACKAGE_VERSION,
+)
+from codefortify_starter.template_engine import TemplateEngine
+
+
+UNRESOLVED_TOKEN_RE = re.compile(r"(\[\[.+?\]\]|\[%.*?%\])", re.DOTALL)
+
+
+@dataclass(frozen=True)
+class GenerationOptions:
+    project_name: str
+    project_slug: str
+    project_title: str
+    project_package: str
+    project_class_name: str
+    target_root: Path
+    database: str
+    use_htmx: bool = False
+    use_drf: bool = False
+    use_docker: bool = False
+    use_celery: bool = False
+    use_git: bool = True
+    force: bool = False
+    package_version: str = PACKAGE_VERSION
+    created_by: str = "codefortify-starter"
+
+    @property
+    def project_path(self) -> Path:
+        return self.target_root / self.project_name
+
+
+@dataclass(frozen=True)
+class GenerationResult:
+    project_path: Path
+    requirements: list[str]
+    warnings: list[str] = field(default_factory=list)
+
+
+class StarterProjectGenerator:
+    """Generates starter projects from base and feature template trees."""
+
+    def __init__(self, template_root: Path | None = None) -> None:
+        self.template_root = template_root or (Path(__file__).resolve().parent / "templates")
+        self.engine = TemplateEngine()
+
+    def generate(self, options: GenerationOptions) -> GenerationResult:
+        warnings: list[str] = []
+        written_paths: set[Path] = set()
+        options.target_root.mkdir(parents=True, exist_ok=True)
+        project_path = options.project_path
+
+        if project_path.exists() and not options.force:
+            raise FileExistsError(f"Destination '{project_path}' already exists. Use --force to overwrite safely.")
+        if project_path.exists() and not project_path.is_dir():
+            raise NotADirectoryError(f"Destination '{project_path}' exists and is not a directory.")
+        project_path.mkdir(parents=True, exist_ok=True)
+
+        context = self._build_context(options)
+        written_paths.update(self._render_base(context, project_path))
+        written_paths.update(self._render_feature_overlays(context, project_path, options))
+
+        requirements = self._build_requirements(options)
+        written_paths.add(self._write_requirements(project_path, requirements))
+        self._assert_no_unresolved_tokens(written_paths)
+
+        if options.use_docker:
+            self._set_executable_bits(project_path)
+            if options.database == "sqlite":
+                warnings.append("Docker + SQLite is supported for development only and is not recommended for production.")
+
+        if options.use_git:
+            warning = self._initialize_git(project_path)
+            if warning:
+                warnings.append(warning)
+
+        return GenerationResult(project_path=project_path, requirements=requirements, warnings=warnings)
+
+    def _render_base(self, context: dict[str, object], project_path: Path) -> set[Path]:
+        base_dir = self.template_root / "base_project"
+        written_paths = self.engine.render_tree(base_dir, project_path, context)
+        (project_path / "media").mkdir(exist_ok=True)
+        media_gitkeep = project_path / "media" / ".gitkeep"
+        media_gitkeep.touch(exist_ok=True)
+        written_paths.add(media_gitkeep)
+        return written_paths
+
+    def _render_feature_overlays(
+        self,
+        context: dict[str, object],
+        project_path: Path,
+        options: GenerationOptions,
+    ) -> set[Path]:
+        written_paths: set[Path] = set()
+        feature_flags = {
+            "htmx": options.use_htmx,
+            "drf": options.use_drf,
+            "docker": options.use_docker,
+            "celery": options.use_celery,
+        }
+        for feature_name, enabled in feature_flags.items():
+            if not enabled:
+                continue
+            feature_dir = self.template_root / "features" / feature_name
+            written_paths.update(self.engine.render_tree(feature_dir, project_path, context))
+        return written_paths
+
+    def _build_context(self, options: GenerationOptions) -> dict[str, object]:
+        return {
+            "project_name": options.project_name,
+            "project_slug": options.project_slug,
+            "project_title": options.project_title,
+            "project_package": options.project_package,
+            "project_class_name": options.project_class_name,
+            "database": options.database,
+            "use_htmx": options.use_htmx,
+            "use_drf": options.use_drf,
+            "use_docker": options.use_docker,
+            "use_celery": options.use_celery,
+            "use_postgres": options.database == "postgres",
+            "use_mysql": options.database == "mysql",
+            "use_sqlite": options.database == "sqlite",
+            "use_git": options.use_git,
+            "package_version": options.package_version,
+            "created_by": options.created_by,
+        }
+
+    def _build_requirements(self, options: GenerationOptions) -> list[str]:
+        dependencies: list[str] = list(BASE_REQUIREMENTS)
+
+        if options.use_htmx:
+            dependencies.extend(FEATURE_REQUIREMENTS["htmx"])
+        if options.use_drf:
+            dependencies.extend(FEATURE_REQUIREMENTS["drf"])
+        if options.use_docker:
+            dependencies.extend(FEATURE_REQUIREMENTS["docker"])
+        if options.use_celery:
+            dependencies.extend(FEATURE_REQUIREMENTS["celery"])
+
+        dependencies.extend(DATABASE_REQUIREMENTS[options.database])
+
+        # Stable dedupe order
+        deduped = list(dict.fromkeys(dependencies))
+        return deduped
+
+    def _write_requirements(self, project_path: Path, dependencies: list[str]) -> Path:
+        requirements_path = project_path / "requirements.txt"
+        body = "\n".join(dependencies) + "\n"
+        requirements_path.write_text(body, encoding="utf-8")
+        return requirements_path
+
+    def _set_executable_bits(self, project_path: Path) -> None:
+        for relative_path in EXECUTABLE_FILES:
+            file_path = project_path / relative_path
+            if not file_path.exists():
+                continue
+            mode = file_path.stat().st_mode
+            file_path.chmod(mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+    def _assert_no_unresolved_tokens(self, paths: set[Path]) -> None:
+        for path in sorted(paths):
+            if not path.exists() or not path.is_file():
+                continue
+            try:
+                content = path.read_text(encoding="utf-8")
+            except UnicodeDecodeError:
+                continue
+            if UNRESOLVED_TOKEN_RE.search(content):
+                raise RuntimeError(f"Unresolved template token found in generated file: {path}")
+
+    def _initialize_git(self, project_path: Path) -> str | None:
+        try:
+            completed = subprocess.run(
+                ["git", "init"],
+                cwd=project_path,
+                check=False,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.PIPE,
+                text=True,
+            )
+        except FileNotFoundError:
+            return "Git is not installed; skipped repository initialization."
+
+        if completed.returncode != 0:
+            message = (completed.stderr or "").strip() or "Unknown git init failure."
+            return f"Failed to initialize git repository: {message}"
+
+        # Avoid hard failure if user shell/environment does not support this command.
+        subprocess.run(
+            ["git", "symbolic-ref", "HEAD", "refs/heads/main"],
+            cwd=project_path,
+            check=False,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+        return None
+
+
+def build_generation_options(
+    *,
+    project_name: str,
+    project_slug: str,
+    project_title: str,
+    project_package: str,
+    project_class_name: str,
+    directory: Path,
+    database: str,
+    use_htmx: bool,
+    use_drf: bool,
+    use_docker: bool,
+    use_celery: bool,
+    no_git: bool,
+    force: bool,
+) -> GenerationOptions:
+    created_by = os.environ.get("USER") or os.environ.get("USERNAME") or "codefortify"
+    return GenerationOptions(
+        project_name=project_name,
+        project_slug=project_slug,
+        project_title=project_title,
+        project_package=project_package,
+        project_class_name=project_class_name,
+        target_root=directory,
+        database=database,
+        use_htmx=use_htmx,
+        use_drf=use_drf,
+        use_docker=use_docker,
+        use_celery=use_celery,
+        use_git=not no_git,
+        force=force,
+        created_by=created_by,
+    )

codefortify_starter/template_engine.py

@@ -0,0 +1,63 @@
+"""Filesystem + Jinja template rendering utilities."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from jinja2 import Environment, StrictUndefined
+
+
+class TemplateEngine:
+    """Renders template trees using custom Jinja delimiters."""
+
+    def __init__(self) -> None:
+        self._environment = Environment(
+            autoescape=False,
+            keep_trailing_newline=True,
+            trim_blocks=False,
+            lstrip_blocks=False,
+            undefined=StrictUndefined,
+            variable_start_string="[[",
+            variable_end_string="]]",
+            block_start_string="[%",  # avoids collision with Django template tags
+            block_end_string="%]",
+        )
+
+    def render_tree(self, source_root: Path, destination_root: Path, context: dict[str, object]) -> set[Path]:
+        """Render files from `source_root` into `destination_root`."""
+        written_paths: set[Path] = set()
+        if not source_root.exists():
+            return written_paths
+
+        for source_path in sorted(source_root.rglob("*")):
+            relative = source_path.relative_to(source_root)
+            destination_path = destination_root / self._normalized_relative_path(relative)
+            if source_path.is_dir():
+                destination_path.mkdir(parents=True, exist_ok=True)
+                continue
+
+            destination_path.parent.mkdir(parents=True, exist_ok=True)
+            if source_path.suffix == ".jinja":
+                rendered = self.render_text(source_path.read_text(encoding="utf-8"), context)
+                destination_path.write_text(rendered, encoding="utf-8")
+            else:
+                shutil.copy2(source_path, destination_path)
+            written_paths.add(destination_path)
+
+        return written_paths
+
+    def render_text(self, template_source: str, context: dict[str, object]) -> str:
+        template = self._environment.from_string(template_source)
+        return template.render(**context)
+
+    def _normalized_relative_path(self, relative_path: Path) -> Path:
+        parts = []
+        for part in relative_path.parts:
+            normalized = part
+            if normalized.startswith("dot-"):
+                normalized = f".{normalized[4:]}"
+            if normalized.endswith(".jinja"):
+                normalized = normalized[: -len(".jinja")]
+            parts.append(normalized)
+        return Path(*parts)

codefortify_starter/templates/base_project/README.md.jinja

@@ -0,0 +1,87 @@
+# [[ project_title ]]
+
+Generated with `codefortify-starter` ([[ package_version ]]).
+
+## Selected features
+
+- Database: `[[ database ]]`
+- HTMX: `[% if use_htmx %]enabled[% else %]disabled[% endif %]`
+- DRF: `[% if use_drf %]enabled[% else %]disabled[% endif %]`
+- Docker: `[% if use_docker %]enabled[% else %]disabled[% endif %]`
+- Celery: `[% if use_celery %]enabled[% else %]disabled[% endif %]`
+
+## Quick start
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+cp .env.example .env
+python manage.py migrate
+python manage.py runserver
+```
+
+Run checks:
+
+```bash
+python manage.py check
+python manage.py test
+```
+
+[% if use_drf %]
+## API
+
+Base API route:
+
+- `GET /api/health/`
+
+[% endif %]
+[% if use_htmx %]
+## HTMX
+
+HTMX demo endpoint:
+
+- `GET /htmx/example/`
+
+[% endif %]
+[% if use_celery %]
+## Celery
+
+Run worker locally:
+
+```bash
+celery -A core worker -l info
+```
+
+Redis must be available at `REDIS_URL`.
+
+[% endif %]
+[% if use_docker %]
+## Docker
+
+Development compose:
+
+```bash
+docker compose up -d --build
+docker compose exec web python manage.py check
+```
+
+See `DOCKER_README.md` for deployment details.
+
+[% endif %]
+## Project layout
+
+```
+.
+|-- apps/
+|   |-- home/
+[% if use_drf %]|   `-- api/
+[% endif %]|-- core/
+|   `-- settings/
+|-- templates/
+|-- static/
+|-- media/
+|-- requirements.txt
+`-- manage.py
+```
+

codefortify_starter/templates/base_project/apps/__init__.py

@@ -0,0 +1 @@
+

codefortify_starter/templates/base_project/apps/home/__init__.py

@@ -0,0 +1 @@
+

codefortify_starter/templates/base_project/apps/home/apps.py.jinja

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class HomeConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "apps.home"
+

codefortify_starter/templates/base_project/apps/home/templates/home/index.html.jinja

@@ -0,0 +1,25 @@
+{% extends "base.html" %}
+
+{% block title %}Home | [[ project_title ]]{% endblock %}
+
+{% block content %}
+<h1>[[ project_title ]]</h1>
+<p>Generated with codefortify-starter.</p>
+
+[% if use_htmx %]
+<section>
+    <button
+        hx-get="{% url 'home:htmx-example' %}"
+        hx-target="#htmx-fragment"
+        hx-swap="innerHTML"
+        type="button"
+    >
+        Load HTMX Fragment
+    </button>
+    <div id="htmx-fragment">
+        {% include "partials/example.html" %}
+    </div>
+</section>
+[% endif %]
+{% endblock %}
+

codefortify_starter/templates/base_project/apps/home/tests.py.jinja

@@ -0,0 +1,17 @@
+from django.test import TestCase
+from django.urls import reverse
+
+
+class HomeViewTests(TestCase):
+    def test_home_page_renders(self):
+        response = self.client.get(reverse("home:home"))
+        self.assertEqual(response.status_code, 200)
+        self.assertTemplateUsed(response, "home/index.html")
+
+[% if use_htmx %]
+    def test_htmx_example_partial_renders(self):
+        response = self.client.get(reverse("home:htmx-example"), HTTP_HX_REQUEST="true")
+        self.assertEqual(response.status_code, 200)
+        self.assertTemplateUsed(response, "partials/example.html")
+[% endif %]
+

codefortify_starter/templates/base_project/apps/home/urls.py.jinja

@@ -0,0 +1,14 @@
+from django.urls import path
+
+from apps.home.views import HomeView[% if use_htmx %], htmx_example[% endif %]
+
+
+app_name = "home"
+
+urlpatterns = [
+    path("", HomeView.as_view(), name="home"),
+[% if use_htmx %]
+    path("htmx/example/", htmx_example, name="htmx-example"),
+[% endif %]
+]
+

codefortify_starter/templates/base_project/apps/home/views.py.jinja

@@ -0,0 +1,13 @@
+from django.shortcuts import render
+from django.views.generic import TemplateView
+
+
+class HomeView(TemplateView):
+    template_name = "home/index.html"
+
+
+[% if use_htmx %]
+def htmx_example(request):
+    return render(request, "partials/example.html")
+[% endif %]
+

codefortify_starter/templates/base_project/core/__init__.py.jinja

@@ -0,0 +1,7 @@
+[% if use_celery %]
+from core.celery import app as celery_app
+[% endif %]
+
+__version__ = "1.0.0"
+
+__all__ = ["__version__"[% if use_celery %], "celery_app"[% endif %]]

codefortify_starter/templates/base_project/core/asgi.py.jinja

@@ -0,0 +1,10 @@
+from core.env import configure_environment
+
+
+configure_environment()
+
+from django.core.asgi import get_asgi_application
+
+
+application = get_asgi_application()
+