django-starter-cdc 0.1.0__tar.gz

django_starter_cdc-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+.idea
+.vscode
+*.code-workspace
+*.pyc
+*~
+.venv
+venv
+db.sqlite3
+.sass-cache/
+celerybeat-schedule
+chrisdevcode/localsettings.py
+chrisdevcode/local.py
+static_root/
+node_modules/
+# ai assistants
+.playwright-mcp/
+.claude/settings.local.json
+media/
+docs/_build
+_dist/
+cli/dist/
+.env
+.env.prod
+.env.production
+.DS_Store
+.direnv
+.envrc
+# built CSS and vendored JS/fonts (npm run build)
+static/css/
+static/vendor/

django_starter_cdc-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Chris Achinga
+Copyright (c) 2026 Elodin Labs LLC (SaaS Pegasus)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_starter_cdc-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.5
+Name: django-starter-cdc
+Version: 0.1.0
+Summary: Generate a new Django 6.1 project from django-starter: full-stack (HTMX, Alpine.js, Tailwind) or API-only.
+Project-URL: Homepage, https://github.com/achingachris/django-starter
+Project-URL: Source, https://github.com/achingachris/django-starter
+Project-URL: Issues, https://github.com/achingachris/django-starter/issues
+Author: Chris Achinga
+License-Expression: MIT
+License-File: LICENSE
+Keywords: allauth,django,drf,generator,htmx,starter,template
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 6.1
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# django-starter-cdc
+
+Generate a new Django 6.1 project from [django-starter](https://github.com/achingachris/django-starter):
+either a full-stack app (Django templates, HTMX, Alpine.js, Tailwind) or an API-only backend
+(Django REST Framework + allauth headless).
+
+The generator has no dependencies of its own. It needs **Python 3.14 or newer**: on an older Python,
+pip stops with "requires a different Python". The projects it creates are managed with
+[uv](https://docs.astral.sh/uv/) (plus npm for the full variant), so install uv however you install
+the generator.
+
+## Install
+
+**With uv (recommended).** `uvx` runs the generator in a throwaway environment, so there is nothing to
+install or upgrade, and uv fetches Python 3.14 for you if needed:
+
+```bash
+uvx django-starter-cdc new myproject
+```
+
+**With pip and a virtual environment.** Following the
+[Python Packaging User Guide](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/),
+create and activate a virtual environment with Python 3.14, then install the package into it:
+
+```bash
+python3.14 -m venv .venv
+source .venv/bin/activate          # Windows: .venv\Scripts\activate
+python -m pip install --upgrade pip
+python -m pip install django-starter-cdc
+django-starter-cdc --version
+```
+
+Run `deactivate` when you're done. `python -m django_starter_cdc` works too, in place of the
+`django-starter-cdc` command. To upgrade later, run `python -m pip install --upgrade django-starter-cdc`.
+
+**With pipx**, to keep the command available everywhere without managing a virtual environment yourself:
+
+```bash
+pipx install --python python3.14 django-starter-cdc
+```
+
+## Usage
+
+```bash
+django-starter-cdc new myproject          # full variant
+django-starter-cdc new myproject --api    # API-only variant
+```
+
+(With uv, prefix these with `uvx`.)
+
+This downloads the django-starter release that matches the generator's version, renders the
+chosen variant into `./myproject`, writes a `.env` with a fresh `SECRET_KEY`, runs `git init`
+and then `make init` (installs dependencies and migrates the SQLite database). Then:
+
+```bash
+cd myproject
+make start
+```
+
+and open <http://localhost:8000/admin/> and <http://localhost:8000/api/schema/swagger-ui/>.
+
+### Options
+
+```
+django-starter-cdc new <name> [--api] [--email EMAIL] [--ref REF | --source PATH]
+                              [--no-install] [--no-git] [--dir PATH]
+```
+
+| Option | What it does |
+| --- | --- |
+| `<name>` | Project name: a lowercase slug of letters, digits, `-` and `_` that starts with a letter. Used for the directory, the Python/npm package name and the `<NAME>_` env-var prefix. |
+| `--api` | Generate the API-only variant (see below). |
+| `--email EMAIL` | Address used for `ADMINS`, `DEFAULT_FROM_EMAIL` and the API contact (default `admin@example.com`). |
+| `--ref REF` | Download a branch, tag or commit instead of the matching release, e.g. `--ref main`. |
+| `--source PATH` | Copy a local django-starter checkout instead of downloading. `.git`, `node_modules`, `.venv`, `.env`, `db.sqlite3` and build output are left out. |
+| `--no-install` | Skip `make init`; the manual setup steps are printed instead. |
+| `--no-git` | Skip `git init`. |
+| `--dir PATH` | Parent directory to create the project in (default: the current directory). |
+
+The target directory must not exist or must be empty. If `make`, `uv` or (for the full variant) `npm`
+is not installed, the generator skips `make init` and prints the equivalent steps:
+`uv sync`, `npm install && npm run build` (full only) and `uv run python manage.py migrate`.
+
+## Variants
+
+Both variants share the same core: Django 6.1 on Python 3.14, a custom user model, `django-allauth`
+with headless mode, Django REST Framework with a `drf-spectacular` OpenAPI schema, Django's built-in
+tasks framework, SQLite for local development and a Docker Compose stack (Postgres + Redis + gunicorn)
+for production.
+
+**Full (default)** adds the server-rendered web app: Django templates, HTMX and Alpine.js for
+interactivity, Tailwind CSS 4 built with the Tailwind CLI (no JavaScript bundler), allauth's account
+pages, a profile page, sitemaps and meta tags.
+
+**API-only (`--api`)** has no templates (other than the allauth email templates), no front-end assets
+and no npm. allauth runs with `HEADLESS_ONLY = True`, so authentication is a JSON API meant for a
+separate front end or mobile app.
+
+## Authentication API
+
+allauth headless serves its auth API under `/_allauth/`. Mobile and other non-browser clients use the
+`app` client, which authenticates with a session token instead of cookies:
+
+| Endpoint | Purpose |
+| --- | --- |
+| `POST /_allauth/app/v1/auth/signup` | Create an account. |
+| `POST /_allauth/app/v1/auth/login` | Log in with email and password. |
+| `GET /_allauth/app/v1/auth/session` | Check the current session. |
+| `DELETE /_allauth/app/v1/auth/session` | Log out. |
+
+A successful signup or login returns `meta.session_token`. Send it as the `X-Session-Token` header on
+later requests, both to the allauth endpoints and to your own API views:
+
+```bash
+curl -s -X POST http://localhost:8000/_allauth/app/v1/auth/login \
+  -H 'Content-Type: application/json' \
+  -d '{"email": "you@example.com", "password": "..."}'
+
+curl -s http://localhost:8000/api/users/me/ -H 'X-Session-Token: <session_token>'
+```
+
+`GET /api/users/me/` is the sample DRF endpoint: it returns the logged-in user. While `DEBUG` is on,
+the full allauth API reference is served at <http://localhost:8000/_allauth/openapi.html>, and your
+own DRF endpoints are documented at <http://localhost:8000/api/schema/swagger-ui/>.
+
+Browser front ends can use the `browser` client (`/_allauth/browser/v1/...`), which uses Django's
+session cookie and CSRF token. A browser SPA served from another origin (for example a Vite dev server
+on port 5173) will also want [`django-cors-headers`](https://pypi.org/project/django-cors-headers/)
+to allow its origin.
+
+## License
+
+MIT

django_starter_cdc-0.1.0/README.md

@@ -0,0 +1,133 @@
+# django-starter-cdc
+
+Generate a new Django 6.1 project from [django-starter](https://github.com/achingachris/django-starter):
+either a full-stack app (Django templates, HTMX, Alpine.js, Tailwind) or an API-only backend
+(Django REST Framework + allauth headless).
+
+The generator has no dependencies of its own. It needs **Python 3.14 or newer**: on an older Python,
+pip stops with "requires a different Python". The projects it creates are managed with
+[uv](https://docs.astral.sh/uv/) (plus npm for the full variant), so install uv however you install
+the generator.
+
+## Install
+
+**With uv (recommended).** `uvx` runs the generator in a throwaway environment, so there is nothing to
+install or upgrade, and uv fetches Python 3.14 for you if needed:
+
+```bash
+uvx django-starter-cdc new myproject
+```
+
+**With pip and a virtual environment.** Following the
+[Python Packaging User Guide](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/),
+create and activate a virtual environment with Python 3.14, then install the package into it:
+
+```bash
+python3.14 -m venv .venv
+source .venv/bin/activate          # Windows: .venv\Scripts\activate
+python -m pip install --upgrade pip
+python -m pip install django-starter-cdc
+django-starter-cdc --version
+```
+
+Run `deactivate` when you're done. `python -m django_starter_cdc` works too, in place of the
+`django-starter-cdc` command. To upgrade later, run `python -m pip install --upgrade django-starter-cdc`.
+
+**With pipx**, to keep the command available everywhere without managing a virtual environment yourself:
+
+```bash
+pipx install --python python3.14 django-starter-cdc
+```
+
+## Usage
+
+```bash
+django-starter-cdc new myproject          # full variant
+django-starter-cdc new myproject --api    # API-only variant
+```
+
+(With uv, prefix these with `uvx`.)
+
+This downloads the django-starter release that matches the generator's version, renders the
+chosen variant into `./myproject`, writes a `.env` with a fresh `SECRET_KEY`, runs `git init`
+and then `make init` (installs dependencies and migrates the SQLite database). Then:
+
+```bash
+cd myproject
+make start
+```
+
+and open <http://localhost:8000/admin/> and <http://localhost:8000/api/schema/swagger-ui/>.
+
+### Options
+
+```
+django-starter-cdc new <name> [--api] [--email EMAIL] [--ref REF | --source PATH]
+                              [--no-install] [--no-git] [--dir PATH]
+```
+
+| Option | What it does |
+| --- | --- |
+| `<name>` | Project name: a lowercase slug of letters, digits, `-` and `_` that starts with a letter. Used for the directory, the Python/npm package name and the `<NAME>_` env-var prefix. |
+| `--api` | Generate the API-only variant (see below). |
+| `--email EMAIL` | Address used for `ADMINS`, `DEFAULT_FROM_EMAIL` and the API contact (default `admin@example.com`). |
+| `--ref REF` | Download a branch, tag or commit instead of the matching release, e.g. `--ref main`. |
+| `--source PATH` | Copy a local django-starter checkout instead of downloading. `.git`, `node_modules`, `.venv`, `.env`, `db.sqlite3` and build output are left out. |
+| `--no-install` | Skip `make init`; the manual setup steps are printed instead. |
+| `--no-git` | Skip `git init`. |
+| `--dir PATH` | Parent directory to create the project in (default: the current directory). |
+
+The target directory must not exist or must be empty. If `make`, `uv` or (for the full variant) `npm`
+is not installed, the generator skips `make init` and prints the equivalent steps:
+`uv sync`, `npm install && npm run build` (full only) and `uv run python manage.py migrate`.
+
+## Variants
+
+Both variants share the same core: Django 6.1 on Python 3.14, a custom user model, `django-allauth`
+with headless mode, Django REST Framework with a `drf-spectacular` OpenAPI schema, Django's built-in
+tasks framework, SQLite for local development and a Docker Compose stack (Postgres + Redis + gunicorn)
+for production.
+
+**Full (default)** adds the server-rendered web app: Django templates, HTMX and Alpine.js for
+interactivity, Tailwind CSS 4 built with the Tailwind CLI (no JavaScript bundler), allauth's account
+pages, a profile page, sitemaps and meta tags.
+
+**API-only (`--api`)** has no templates (other than the allauth email templates), no front-end assets
+and no npm. allauth runs with `HEADLESS_ONLY = True`, so authentication is a JSON API meant for a
+separate front end or mobile app.
+
+## Authentication API
+
+allauth headless serves its auth API under `/_allauth/`. Mobile and other non-browser clients use the
+`app` client, which authenticates with a session token instead of cookies:
+
+| Endpoint | Purpose |
+| --- | --- |
+| `POST /_allauth/app/v1/auth/signup` | Create an account. |
+| `POST /_allauth/app/v1/auth/login` | Log in with email and password. |
+| `GET /_allauth/app/v1/auth/session` | Check the current session. |
+| `DELETE /_allauth/app/v1/auth/session` | Log out. |
+
+A successful signup or login returns `meta.session_token`. Send it as the `X-Session-Token` header on
+later requests, both to the allauth endpoints and to your own API views:
+
+```bash
+curl -s -X POST http://localhost:8000/_allauth/app/v1/auth/login \
+  -H 'Content-Type: application/json' \
+  -d '{"email": "you@example.com", "password": "..."}'
+
+curl -s http://localhost:8000/api/users/me/ -H 'X-Session-Token: <session_token>'
+```
+
+`GET /api/users/me/` is the sample DRF endpoint: it returns the logged-in user. While `DEBUG` is on,
+the full allauth API reference is served at <http://localhost:8000/_allauth/openapi.html>, and your
+own DRF endpoints are documented at <http://localhost:8000/api/schema/swagger-ui/>.
+
+Browser front ends can use the `browser` client (`/_allauth/browser/v1/...`), which uses Django's
+session cookie and CSRF token. A browser SPA served from another origin (for example a Vite dev server
+on port 5173) will also want [`django-cors-headers`](https://pypi.org/project/django-cors-headers/)
+to allow its origin.
+
+## License
+
+MIT

django_starter_cdc-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "django-starter-cdc"
+dynamic = ["version"]
+description = "Generate a new Django 6.1 project from django-starter: full-stack (HTMX, Alpine.js, Tailwind) or API-only."
+readme = "README.md"
+requires-python = ">=3.14"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Chris Achinga" }]
+keywords = ["django", "starter", "template", "generator", "htmx", "allauth", "drf"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Framework :: Django",
+    "Framework :: Django :: 6.1",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Code Generators",
+]
+dependencies = []
+
+[project.scripts]
+django-starter-cdc = "django_starter_cdc.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/achingachris/django-starter"
+Source = "https://github.com/achingachris/django-starter"
+Issues = "https://github.com/achingachris/django-starter/issues"
+
+# The version is read from __version__, which the CLI also uses to pick the release tarball to download.
+[tool.hatch.version]
+path = "src/django_starter_cdc/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/django_starter_cdc"]
+
+[tool.uv]
+# uv rebuilds a local path package only when its cache keys change (pyproject.toml by default), so
+# `uvx --from ./cli` would keep running a stale build after edits to the source. Include the source.
+cache-keys = [{ file = "pyproject.toml" }, { file = "README.md" }, { file = "src/**/*.py" }]
+
+[tool.ruff]
+line-length = 120
+target-version = "py314"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.ruff.format]
+quote-style = "double"

django_starter_cdc-0.1.0/src/django_starter_cdc/__init__.py

@@ -0,0 +1,3 @@
+"""Generate a new Django project from the django-starter template."""
+
+__version__ = "0.1.0"

django_starter_cdc-0.1.0/src/django_starter_cdc/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from django_starter_cdc.cli import main
+
+sys.exit(main())

django_starter_cdc-0.1.0/src/django_starter_cdc/cli.py

@@ -0,0 +1,147 @@
+"""Command line entry point: ``django-starter-cdc new <name> [options]``."""
+
+import argparse
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from django_starter_cdc import __version__
+from django_starter_cdc.fetch import FetchError, archive_url, copy_local, download
+from django_starter_cdc.render import DEFAULT_EMAIL, RenderError, render_project
+
+# A lowercase slug that starts with a letter and ends with a letter or digit, e.g. "shop" or "my-shop_2".
+NAME_RE = re.compile(r"^[a-z](?:[a-z0-9_-]*[a-z0-9])?$")
+EMAIL_RE = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
+
+
+class CLIError(Exception):
+    """Invalid input from the command line."""
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="django-starter-cdc",
+        description="Generate a new Django 6.1 project from django-starter.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True, metavar="command")
+
+    new = commands.add_parser(
+        "new",
+        help="create a new project",
+        description="Create a new project. The full variant has templates, HTMX, Alpine.js and Tailwind; "
+        "--api gives an API-only project (DRF + allauth headless, no templates or npm).",
+    )
+    new.add_argument("name", help="project name: a lowercase slug of letters, digits, hyphens and underscores")
+    new.add_argument("--api", action="store_true", help="API-only variant: no templates, front end or npm")
+    new.add_argument(
+        "--email", default=DEFAULT_EMAIL, help=f"admin and default from-address email (default: {DEFAULT_EMAIL})"
+    )
+    source = new.add_mutually_exclusive_group()
+    source.add_argument(
+        "--ref",
+        help=f"git ref (branch, tag or commit) to download instead of the v{__version__} release, e.g. main",
+    )
+    source.add_argument("--source", type=Path, metavar="PATH", help="copy a local django-starter checkout instead")
+    new.add_argument("--no-install", action="store_true", help="skip `make init` (dependencies and migrations)")
+    new.add_argument("--no-git", action="store_true", help="skip `git init`")
+    new.add_argument(
+        "--dir", type=Path, default=Path("."), metavar="PATH", help="parent directory for the project (default: .)"
+    )
+    return parser
+
+
+def validate(args: argparse.Namespace) -> Path:
+    """Check the name, email and target directory. Returns the project directory to create."""
+    if not NAME_RE.match(args.name):
+        raise CLIError(
+            f"Invalid project name {args.name!r}: use lowercase letters, digits, hyphens and underscores, "
+            "starting with a letter and ending with a letter or digit."
+        )
+    if not EMAIL_RE.match(args.email):
+        raise CLIError(f"Invalid email address {args.email!r}.")
+    target = args.dir.expanduser().resolve() / args.name
+    if target.exists() and (not target.is_dir() or any(target.iterdir())):
+        raise CLIError(f"{target} already exists and is not an empty directory.")
+    return target
+
+
+def run(command: list[str], cwd: Path) -> bool:
+    print(f"$ {' '.join(command)}")
+    return subprocess.run(command, cwd=cwd).returncode == 0
+
+
+def manual_steps(name: str, api: bool) -> list[str]:
+    steps = [f"cd {name}", "uv sync"]
+    if not api:
+        steps.append("npm install && npm run build")
+    steps.append("uv run python manage.py migrate")
+    return steps
+
+
+def install(target: Path, api: bool) -> bool:
+    """Run `make init` when its tools are available. Returns False if the user has to finish setup by hand."""
+    tools = ["make", "uv"] if api else ["make", "uv", "npm"]
+    missing = [tool for tool in tools if shutil.which(tool) is None]
+    if missing:
+        print(f"\nSkipping `make init`: {', '.join(missing)} not found on PATH.")
+        return False
+    if run(["make", "init"], target):
+        return True
+    print("\n`make init` failed; see the output above.", file=sys.stderr)
+    return False
+
+
+def print_next_steps(target: Path, api: bool, installed: bool) -> None:
+    print(f"\nCreated {'API-only' if api else 'full'} project in {target}\n")
+    if installed:
+        print("Next steps:\n")
+        print(f"  cd {target.name}")
+    else:
+        print("Finish the setup:\n")
+        print("\n".join(f"  {step}" for step in manual_steps(target.name, api)))
+    print("  make start\n")
+    print("Then open:")
+    print("  http://localhost:8000/admin/                  Django admin")
+    print("  http://localhost:8000/api/schema/swagger-ui/  API docs")
+    if api:
+        print("  http://localhost:8000/_allauth/openapi.html   auth API docs (allauth headless)")
+
+
+def create_project(args: argparse.Namespace) -> int:
+    target = validate(args)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(prefix=f".{args.name}-", dir=target.parent) as tmp:
+        stage = Path(tmp) / args.name
+        if args.source:
+            print(f"Copying {args.source.resolve()}")
+            copy_local(args.source, stage, exclude=(Path(tmp), target))
+        else:
+            print(f"Downloading {archive_url(args.ref)}")
+            download(stage, args.ref)
+        print(f"Rendering the {'API-only' if args.api else 'full'} variant")
+        render_project(stage, api=args.api, slug=args.name, email=args.email)
+        if target.exists():
+            target.rmdir()
+        stage.rename(target)
+
+    if not args.no_git:
+        if shutil.which("git"):
+            run(["git", "init", "-q"], target)
+        else:
+            print("Skipping `git init`: git not found on PATH.")
+    installed = not args.no_install and install(target, args.api)
+    print_next_steps(target, args.api, installed)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return create_project(args)
+    except (CLIError, FetchError, RenderError, OSError) as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1

django_starter_cdc-0.1.0/src/django_starter_cdc/fetch.py

@@ -0,0 +1,108 @@
+"""Get the django-starter source tree: from a local checkout or a GitHub release tarball."""
+
+import shutil
+import tarfile
+import tempfile
+import urllib.error
+import urllib.request
+from collections.abc import Iterable
+from pathlib import Path
+
+from django_starter_cdc import __version__
+
+REPO_URL = "https://github.com/achingachris/django-starter"
+
+# Skipped by name wherever they appear in a local checkout.
+IGNORED_NAMES = frozenset(
+    {
+        ".git",
+        "node_modules",
+        ".venv",
+        "__pycache__",
+        ".ruff_cache",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".DS_Store",
+        ".idea",
+        ".vscode",
+        ".playwright-mcp",
+    }
+)
+
+# Skipped only at these paths, relative to the checkout root: build output, local data and secrets.
+IGNORED_PATHS = frozenset(
+    {
+        "cli",
+        "db.sqlite3",
+        "static/vendor",
+        "static/css",
+        "static_root",
+        "media",
+        ".env",
+        ".env.prod",
+        ".claude/settings.local.json",
+    }
+)
+
+
+class FetchError(Exception):
+    """The template source could not be copied or downloaded."""
+
+
+def archive_url(ref: str | None = None) -> str:
+    """URL of the source tarball: the release tag matching this CLI's version, or any git ref."""
+    if ref:
+        return f"{REPO_URL}/archive/{ref}.tar.gz"
+    return f"{REPO_URL}/archive/refs/tags/v{__version__}.tar.gz"
+
+
+def copy_local(source: Path, dest: Path, exclude: Iterable[Path] = ()) -> None:
+    """Copy a local checkout into ``dest``, leaving out VCS data, dependencies, build output and secrets.
+
+    ``exclude`` lists further paths to skip. The CLI passes its staging directory and the target, which sit
+    inside the checkout when a project is generated there (e.g. ``new sample --source .``); copying them
+    would make the copy recurse into itself.
+    """
+    source = source.resolve()
+    if not (source / "manage.py").is_file():
+        raise FetchError(f"{source} does not look like a django-starter checkout (no manage.py).")
+    excluded = {Path(p).resolve() for p in exclude}
+
+    def ignore(directory: str, names: list[str]) -> set[str]:
+        rel_dir = Path(directory).resolve().relative_to(source)
+        ignored = set()
+        for name in names:
+            rel = (rel_dir / name).as_posix()
+            if name in IGNORED_NAMES or rel in IGNORED_PATHS or (Path(directory) / name).resolve() in excluded:
+                ignored.add(name)
+        return ignored
+
+    shutil.copytree(source, dest, ignore=ignore, symlinks=True)
+
+
+def download(dest: Path, ref: str | None = None) -> None:
+    """Download and extract the source tarball into ``dest``, stripping its single top-level folder."""
+    url = archive_url(ref)
+    with tempfile.TemporaryDirectory(prefix="django-starter-cdc-") as tmp:
+        archive = Path(tmp) / "source.tar.gz"
+        request = urllib.request.Request(url, headers={"User-Agent": f"django-starter-cdc/{__version__}"})
+        try:
+            with urllib.request.urlopen(request, timeout=60) as response, archive.open("wb") as fh:
+                shutil.copyfileobj(response, fh)
+        except urllib.error.HTTPError as e:
+            hint = "" if ref else " Pass --ref main to use the latest code instead of a release."
+            raise FetchError(f"Could not download {url}: HTTP {e.code}.{hint}") from e
+        except urllib.error.URLError as e:
+            raise FetchError(f"Could not download {url}: {e.reason}") from e
+
+        extracted = Path(tmp) / "extracted"
+        try:
+            with tarfile.open(archive, "r:gz") as tar:
+                tar.extractall(extracted, filter="data")
+        except (tarfile.TarError, OSError) as e:
+            raise FetchError(f"Could not extract {url}: {e}") from e
+
+        entries = list(extracted.iterdir())
+        if len(entries) != 1 or not entries[0].is_dir():
+            raise FetchError(f"Unexpected archive layout in {url}: expected a single top-level folder.")
+        shutil.move(entries[0], dest)

django_starter_cdc-0.1.0/src/django_starter_cdc/render.py

@@ -0,0 +1,192 @@
+"""Turn a django-starter source tree into a new project: variant markers, pruning, renaming and ``.env``."""
+
+import os
+import re
+import secrets
+from pathlib import Path
+
+# `# >>> web`, `<!-- >>> web -->` or `{# >>> web #}` opens a block; `<<< web` closes it. A `web` block is kept
+# (without its markers) in the full variant and dropped from the API variant. A `starter` block holds text that
+# only makes sense in the starter repo itself and is always dropped.
+BLOCK_MARKER = re.compile(r"^\s*(#|<!--|\{#)\s*(>>>|<<<)\s*(web|starter)\b")
+
+# `# api-only: <code>` is a commented-out line that the API variant uncomments.
+API_ONLY = re.compile(r"^(\s*)# api-only: (.*)$")
+
+# Removed from the API variant. Entries ending in "/" are directories.
+API_REMOVED_PATHS = (
+    "templates/",
+    "assets/",
+    "static/css/",
+    "static/javascript/",
+    "static/images/undraw/",
+    "static/images/web/",
+    "package.json",
+    "package-lock.json",
+    ".npmrc",
+    ".github/workflows/build_frontend.yml",
+    "apps/web/views.py",
+    "apps/web/urls.py",
+    "apps/web/forms.py",
+    "apps/web/sitemaps.py",
+    "apps/web/meta.py",
+    "apps/web/context_processors.py",
+    "apps/web/templatetags/",
+    "apps/users/views.py",
+    "apps/users/urls.py",
+    "apps/users/forms.py",
+    "apps/web/tests/test_basic_views.py",
+    "apps/web/tests/test_logged_in_views.py",
+    "apps/web/tests/test_meta_tags.py",
+    "apps/web/tests/test_admin_dashboard.py",
+    "apps/users/tests/test_profile.py",
+    ".cursor/rules/django-templates.mdc",
+    ".cursor/rules/javascript-guidelines.mdc",
+)
+
+# Kept in the API variant even though a parent is in API_REMOVED_PATHS: allauth still sends these emails.
+API_KEPT_PATHS = ("templates/account/email/",)
+
+# Removed from every generated project: the generator itself and the workflows that publish it.
+ALWAYS_REMOVED_PATHS = (
+    "cli/",
+    ".github/workflows/publish_cli.yml",
+    ".github/workflows/starter_cli.yml",
+)
+
+DEFAULT_EMAIL = "admin@example.com"
+
+
+class RenderError(Exception):
+    """The source tree could not be rendered, e.g. because of unbalanced variant markers."""
+
+
+def process_text(text: str, api: bool, path: str = "<text>") -> str:
+    """Apply the web/starter blocks and api-only markers for the chosen variant to one file's text."""
+    out = []
+    # Line number of the open block for each tag, or None. Blocks of different tags may overlap.
+    open_blocks: dict[str, int | None] = {"web": None, "starter": None}
+    for lineno, line in enumerate(text.splitlines(keepends=True), start=1):
+        body = line.rstrip("\r\n")
+        marker = BLOCK_MARKER.match(body)
+        if marker:
+            direction, tag = marker.group(2), marker.group(3)
+            start = open_blocks[tag]
+            if direction == ">>>":
+                if start is not None:
+                    raise RenderError(f"{path}:{lineno}: '>>> {tag}' inside the block opened on line {start}.")
+                open_blocks[tag] = lineno
+            else:
+                if start is None:
+                    raise RenderError(f"{path}:{lineno}: '<<< {tag}' without a matching '>>> {tag}'.")
+                open_blocks[tag] = None
+            continue
+        if open_blocks["starter"] is not None or (api and open_blocks["web"] is not None):
+            continue
+        api_only = API_ONLY.match(body)
+        if api_only:
+            if api:
+                out.append(api_only.group(1) + api_only.group(2) + line[len(body) :])
+            continue
+        out.append(line)
+    for tag, start in open_blocks.items():
+        if start is not None:
+            raise RenderError(f"{path}:{start}: '>>> {tag}' is never closed with '<<< {tag}'.")
+    return "".join(out)
+
+
+def _matches(rel: str, patterns: tuple[str, ...]) -> bool:
+    return any(rel.startswith(p) if p.endswith("/") else rel == p for p in patterns)
+
+
+def removed_paths(api: bool) -> tuple[str, ...]:
+    return ALWAYS_REMOVED_PATHS + API_REMOVED_PATHS if api else ALWAYS_REMOVED_PATHS
+
+
+def prune(root: Path, api: bool) -> list[str]:
+    """Delete the paths that do not belong in the chosen variant. Returns the removed files, relative to root."""
+    patterns = removed_paths(api)
+    removed = []
+    emptied_dirs = set()
+    for dirpath, dirnames, filenames in os.walk(root):
+        directory = Path(dirpath)
+        # Symlinks to directories are listed in dirnames but not walked; remove them like files.
+        links = [d for d in dirnames if (directory / d).is_symlink()]
+        for name in filenames + links:
+            path = directory / name
+            rel = path.relative_to(root).as_posix()
+            if _matches(rel, patterns) and not _matches(rel, API_KEPT_PATHS if api else ()):
+                path.unlink()
+                removed.append(rel)
+                emptied_dirs.add(directory)
+    for directory in sorted(emptied_dirs, key=lambda d: len(d.parts), reverse=True):
+        while directory != root and directory.is_dir() and not any(directory.iterdir()):
+            directory.rmdir()
+            directory = directory.parent
+    return sorted(removed)
+
+
+def rename_map(slug: str, email: str = DEFAULT_EMAIL) -> dict[str, str]:
+    """Template names and contact details mapped to the new project's values."""
+    return {
+        "CHRISDEVCODE_": slug.upper().replace("-", "_") + "_",
+        "chrisdevcode": slug,
+        "django-starter": slug,
+        "django-template": slug,
+        "achinga.chris@gmail.com": email,
+    }
+
+
+def rename(text: str, slug: str, email: str = DEFAULT_EMAIL) -> str:
+    """Replace the template's names in one pass, so a slug containing an old name is not replaced again."""
+    mapping = rename_map(slug, email)
+    pattern = re.compile("|".join(re.escape(k) for k in sorted(mapping, key=len, reverse=True)))
+    return pattern.sub(lambda m: mapping[m.group(0)], text)
+
+
+def read_text(path: Path) -> str | None:
+    """The file's text, or None for binary or non-UTF-8 files."""
+    data = path.read_bytes()
+    if b"\0" in data:
+        return None
+    try:
+        return data.decode("utf-8")
+    except UnicodeDecodeError:
+        return None
+
+
+def render_tree(root: Path, api: bool, slug: str, email: str = DEFAULT_EMAIL) -> None:
+    """Apply the variant markers and renaming to every UTF-8 text file under root."""
+    for dirpath, _dirnames, filenames in os.walk(root):
+        for name in filenames:
+            path = Path(dirpath) / name
+            if path.is_symlink():
+                continue
+            text = read_text(path)
+            if text is None:
+                continue
+            rel = path.relative_to(root).as_posix()
+            new = rename(process_text(text, api, rel), slug, email)
+            if new != text:
+                path.write_text(new, encoding="utf-8", newline="")
+
+
+def write_env(root: Path) -> bool:
+    """Create .env from .env.example with a fresh SECRET_KEY. Returns False if there is no .env.example."""
+    example = root / ".env.example"
+    if not example.is_file():
+        return False
+    text = example.read_bytes().decode("utf-8")
+    secret_line = f'SECRET_KEY="{secrets.token_urlsafe(50)}"'
+    text, count = re.subn(r"^SECRET_KEY=[^\r\n]*", lambda _: secret_line, text, count=1, flags=re.MULTILINE)
+    if not count:
+        text = text.rstrip("\n") + f"\n{secret_line}\n"
+    (root / ".env").write_text(text, encoding="utf-8", newline="")
+    return True
+
+
+def render_project(root: Path, *, api: bool, slug: str, email: str = DEFAULT_EMAIL) -> None:
+    """Turn a copied source tree into the chosen variant of a new project, in place."""
+    prune(root, api)
+    render_tree(root, api, slug, email)
+    write_env(root)

django_starter_cdc-0.1.0/tests/test_render.py

@@ -0,0 +1,242 @@
+import contextlib
+import io
+import tempfile
+import unittest
+from pathlib import Path
+
+from django_starter_cdc.cli import NAME_RE, main
+from django_starter_cdc.fetch import archive_url, copy_local
+from django_starter_cdc.render import RenderError, process_text, prune, rename, render_project, write_env
+
+SETTINGS = """\
+INSTALLED_APPS = [
+    "apps.users",
+    # >>> web
+    "apps.web",
+    # <<< web
+]
+# api-only: HEADLESS_ONLY = True
+"""
+
+TEMPLATE = """\
+<body>
+<!-- >>> web -->
+<nav></nav>
+<!-- <<< web -->
+{# >>> web #}
+<footer></footer>
+{# <<< web #}
+</body>
+"""
+
+
+class ProcessTextTests(unittest.TestCase):
+    def test_full_mode_keeps_blocks_and_drops_markers(self):
+        self.assertEqual(
+            process_text(SETTINGS, api=False),
+            'INSTALLED_APPS = [\n    "apps.users",\n    "apps.web",\n]\n',
+        )
+
+    def test_api_mode_drops_blocks(self):
+        self.assertEqual(
+            process_text(SETTINGS, api=True),
+            'INSTALLED_APPS = [\n    "apps.users",\n]\nHEADLESS_ONLY = True\n',
+        )
+
+    def test_html_and_django_comment_markers(self):
+        self.assertEqual(process_text(TEMPLATE, api=False), "<body>\n<nav></nav>\n<footer></footer>\n</body>\n")
+        self.assertEqual(process_text(TEMPLATE, api=True), "<body>\n</body>\n")
+
+    def test_api_only_keeps_indentation_and_line_endings(self):
+        text = "if True:\r\n    # api-only: x = 1\r\n    y = 2\r\n"
+        self.assertEqual(process_text(text, api=True), "if True:\r\n    x = 1\r\n    y = 2\r\n")
+        self.assertEqual(process_text(text, api=False), "if True:\r\n    y = 2\r\n")
+
+    def test_api_only_inside_web_block_is_dropped_in_api_mode(self):
+        text = "# >>> web\n# api-only: x = 1\n# <<< web\n"
+        self.assertEqual(process_text(text, api=True), "")
+
+    def test_text_without_markers_is_unchanged(self):
+        text = "# a web comment\nwebsite = 'web'\n# >>> website\n"
+        self.assertEqual(process_text(text, api=True), text)
+
+    def test_unclosed_block(self):
+        with self.assertRaisesRegex(RenderError, r"settings.py:2: '>>> web' is never closed"):
+            process_text("x = 1\n# >>> web\ny = 2\n", api=True, path="settings.py")
+
+    def test_close_without_open(self):
+        with self.assertRaisesRegex(RenderError, r"urls.py:1: '<<< web' without a matching"):
+            process_text("# <<< web\n", api=False, path="urls.py")
+
+    def test_nested_open(self):
+        with self.assertRaisesRegex(RenderError, r"Makefile:3: '>>> web' inside the block opened on line 1"):
+            process_text("# >>> web\na\n# >>> web\n# <<< web\n", api=False, path="Makefile")
+
+    def test_starter_blocks_are_dropped_in_both_variants(self):
+        text = (
+            "# Docs\n<!-- >>> starter -->\nRun uvx django-starter-cdc.\n<!-- <<< starter -->\n"
+            "{# >>> starter #}\nx\n{# <<< starter #}\nEnd\n"
+        )
+        for api in (False, True):
+            self.assertEqual(process_text(text, api=api), "# Docs\nEnd\n")
+
+    def test_web_block_inside_starter_block(self):
+        text = "a\n# >>> starter\nb\n# >>> web\nc\n# <<< web\n# <<< starter\nd\n"
+        self.assertEqual(process_text(text, api=False), "a\nd\n")
+
+    def test_unbalanced_starter_markers(self):
+        with self.assertRaisesRegex(RenderError, r"README.md:1: '>>> starter' is never closed"):
+            process_text("<!-- >>> starter -->\n", api=False, path="README.md")
+        with self.assertRaisesRegex(RenderError, r"README.md:2: '<<< starter' without a matching"):
+            process_text("<!-- >>> web -->\n<!-- <<< starter -->\n", api=False, path="README.md")
+
+    def test_makefile_markers_at_column_zero(self):
+        text = (
+            "init:\n\t@uv sync\n# >>> web\n\t@npm install\n# <<< web\n\t@$(MAKE) migrate\n"
+            "# api-only: upgrade: requirements migrate  ## Update\n"
+        )
+        self.assertEqual(
+            process_text(text, api=True),
+            "init:\n\t@uv sync\n\t@$(MAKE) migrate\nupgrade: requirements migrate  ## Update\n",
+        )
+        self.assertEqual(process_text(text, api=False), "init:\n\t@uv sync\n\t@npm install\n\t@$(MAKE) migrate\n")
+
+
+class RenameTests(unittest.TestCase):
+    def test_names_env_prefix_and_email(self):
+        text = (
+            'name = "chrisdevcode"\nimage: django-starter-app\n"""django-template URLs"""\n'
+            'env("CHRISDEVCODE_LOG_LEVEL")\nADMINS = ["achinga.chris@gmail.com"]\n'
+        )
+        self.assertEqual(
+            rename(text, "my-shop", "me@shop.test"),
+            'name = "my-shop"\nimage: my-shop-app\n"""my-shop URLs"""\n'
+            'env("MY_SHOP_LOG_LEVEL")\nADMINS = ["me@shop.test"]\n',
+        )
+
+    def test_default_email(self):
+        self.assertEqual(rename("achinga.chris@gmail.com", "shop"), "admin@example.com")
+
+    def test_slug_containing_an_old_name_is_not_replaced_twice(self):
+        self.assertEqual(
+            rename("django-starter chrisdevcode", "django-template-x"), "django-template-x django-template-x"
+        )
+
+
+class TreeTests(unittest.TestCase):
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        self.root = Path(self._tmp.name) / "project"
+        files = {
+            "manage.py": "print('chrisdevcode')\n",
+            "package.json": '{"name": "chrisdevcode"}\n',
+            "templates/web/base.html": "<html></html>\n",
+            "templates/account/email/base.txt": "{# >>> web #}\nweb\n{# <<< web #}\nemail\n",
+            "apps/web/views.py": "",
+            "apps/web/models.py": "",
+            "apps/web/templatetags/meta_tags.py": "",
+            "apps/users/views.py": "",
+            "apps/users/api.py": "",
+            "cli/pyproject.toml": "",
+            ".github/workflows/tests.yml": "",
+            ".github/workflows/publish_cli.yml": "",
+            ".cursor/rules/django-templates.mdc": "",
+            ".cursor/rules/python.mdc": "",
+            ".env.example": '# header\nSECRET_KEY="django-insecure-x"\nDEBUG=True\n',
+        }
+        for rel, text in files.items():
+            path = self.root / rel
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(text)
+        (self.root / "static/images").mkdir(parents=True)
+        (self.root / "static/images/logo.png").write_bytes(b"\x89PNG\r\n\x1a\n\0\0chrisdevcode")
+
+    def tearDown(self):
+        self._tmp.cleanup()
+
+    def files(self):
+        return sorted(p.relative_to(self.root).as_posix() for p in self.root.rglob("*") if p.is_file())
+
+    def test_prune_full_removes_only_the_cli(self):
+        removed = prune(self.root, api=False)
+        self.assertEqual(removed, [".github/workflows/publish_cli.yml", "cli/pyproject.toml"])
+        self.assertFalse((self.root / "cli").exists())
+        self.assertTrue((self.root / "templates/web/base.html").exists())
+
+    def test_prune_api(self):
+        prune(self.root, api=True)
+        self.assertEqual(
+            self.files(),
+            [
+                ".cursor/rules/python.mdc",
+                ".env.example",
+                ".github/workflows/tests.yml",
+                "apps/users/api.py",
+                "apps/web/models.py",
+                "manage.py",
+                "static/images/logo.png",
+                "templates/account/email/base.txt",
+            ],
+        )
+        self.assertFalse((self.root / "templates/web").exists())
+        self.assertFalse((self.root / "apps/web/templatetags").exists())
+
+    def test_render_project_api(self):
+        render_project(self.root, api=True, slug="shop", email="me@shop.test")
+        self.assertEqual((self.root / "manage.py").read_text(), "print('shop')\n")
+        self.assertEqual((self.root / "templates/account/email/base.txt").read_text(), "email\n")
+        self.assertIn(b"chrisdevcode", (self.root / "static/images/logo.png").read_bytes())
+        env = (self.root / ".env").read_text()
+        self.assertNotIn("django-insecure", env)
+        self.assertRegex(env, r'SECRET_KEY="[\w-]{60,}"\nDEBUG=True\n')
+
+    def test_render_project_reports_the_file_with_bad_markers(self):
+        (self.root / "apps/web/models.py").write_text("# >>> web\n")
+        with self.assertRaisesRegex(RenderError, r"apps/web/models.py:1"):
+            render_project(self.root, api=False, slug="shop")
+
+    def test_write_env_without_example(self):
+        (self.root / ".env.example").unlink()
+        self.assertFalse(write_env(self.root))
+
+    def test_copy_local_skips_build_output_and_secrets(self):
+        for rel in (".env", "db.sqlite3", "node_modules/x.js", "static/css/site.css", "apps/__pycache__/a.pyc"):
+            path = self.root / rel
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text("x")
+        dest = Path(self._tmp.name) / "copy"
+        copy_local(self.root, dest)
+        copied = sorted(p.relative_to(dest).as_posix() for p in dest.rglob("*") if p.is_file())
+        self.assertNotIn(".env", copied)
+        self.assertNotIn("db.sqlite3", copied)
+        self.assertFalse(any(p.startswith(("cli/", "node_modules/", "static/css/")) for p in copied))
+        self.assertFalse(any("__pycache__" in p for p in copied))
+        self.assertIn(".env.example", copied)
+
+    def test_new_project_inside_the_source_checkout(self):
+        # `new sample --source .` with the default `--dir .`: the staging directory and the target both
+        # live inside the checkout being copied, and must not be copied into the project.
+        with contextlib.redirect_stdout(io.StringIO()):
+            args = ["new", "sample", "--source", str(self.root), "--dir", str(self.root), "--no-git", "--no-install"]
+            code = main(args)
+        self.assertEqual(code, 0)
+        project = self.root / "sample"
+        self.assertTrue((project / "manage.py").is_file())
+        self.assertEqual([p.name for p in project.iterdir() if p.name == "sample" or p.name.startswith(".sample-")], [])
+        self.assertEqual([p.name for p in self.root.iterdir() if p.name.startswith(".sample-")], [])
+
+
+class CLITests(unittest.TestCase):
+    def test_name_validation(self):
+        for name in ("shop", "my-shop", "my_shop2", "a"):
+            self.assertRegex(name, NAME_RE)
+        for name in ("Shop", "2shop", "my shop", "shop-", "-shop", "my.shop", ""):
+            self.assertNotRegex(name, NAME_RE)
+
+    def test_archive_url(self):
+        self.assertEqual(archive_url("main"), "https://github.com/achingachris/django-starter/archive/main.tar.gz")
+        self.assertRegex(archive_url(), r"/archive/refs/tags/v\d+\.\d+\.\d+\.tar\.gz$")
+
+
+if __name__ == "__main__":
+    unittest.main()

django_starter_cdc-0.1.0/uv.lock

@@ -0,0 +1,7 @@
+version = 1
+revision = 3
+requires-python = ">=3.14"
+
+[[package]]
+name = "django-starter-cdc"
+source = { editable = "." }