release: v0.16.0 — shimkit framework django

Third framework recipe under the existing `framework` parent.
Modelled on Laravel (v0.7.0) + Symfony (v0.14.0); adjusted for
Django's conventions:

  Aspect           Laravel               Symfony           Django
  ──────────────────────────────────────────────────────────────────
  Writable tree    storage + b/c         var               media + staticfiles
  App secret       APP_KEY base64        APP_SECRET hex    SECRET_KEY 50-char alphabet
  Env file         .env                  .env.local        .env (django-environ)
  Console          artisan               bin/console       manage.py
  Console runtime  php                   php               python
  Scheduler kit    cron-install          —                 migrate (sugar)

Surface (one fewer command than Laravel — no cron-install since
Django has no built-in scheduler, same as Symfony):

    shimkit framework django perms PATH [--group G] (MODERATE)
    shimkit framework django env PATH
        [--name N] [--debug/--no-debug] [--db D] (MODERATE)
    shimkit framework django migrate PATH
    shimkit framework django manage
        --project PATH [--in-container [--stack NAME]] -- <args>

`migrate` is sugar for `manage migrate --no-input` — the most-
common manage.py invocation in any CI / deploy script.

`env` writes django-environ / python-decouple compatible `.env`
with SECRET_KEY + DEBUG + ALLOWED_HOSTS + DATABASE_URL +
EMAIL_BACKEND + a commented REDIS_URL hint pointing at
`shimkit db redis up` (v0.15.0).

SECRET_KEY is hand-rolled to match Django's documented alphabet
(`[a-zA-Z0-9!@#$%^&*(-_=+)]`, 50 chars). shimkit doesn't depend
on Django being installed to scaffold the file.

Default DB is **postgres** (Django's most-shipped pairing —
unlike Laravel's mysql default).

Implementation:

- New `tools/framework/django/` sub-tree (manager + commands +
  __init__) mirroring laravel/ and symfony/.
- `framework_app` registers `django_app` alongside `laravel_app`
  + `symfony_app`. Sub-app surface unchanged for existing users.
- `FrameworkDjangoConfig` pydantic model + corresponding
  defaults.json block with `web_group`, `file_mode`, `dir_mode`,
  `writable_dirs`, `default_debug`.

Tests: 30 new in test_tools_framework_django.py (1086 → 1116
total). _generate_secret_key (length / Django alphabet /
uniqueness across 100 calls), platform gating, perms (path
refusal / dry-run / media + staticfiles targeting / chgrp skip
on missing group / missing-writable warning / failed-step JSON),
env (overwrite refusal / SECRET_KEY shape + DATABASE_URL postgres
default / DEBUG True default / --no-debug / DATABASE_URL mysql +
mariadb / ALLOWED_HOSTS + EMAIL_BACKEND present / Redis hint
commented-out / dry-run no-write / uniqueness across two
scaffolds), manage (host happy path / missing-python exits 69 /
no-args refusal / missing-manage.py refusal / --in-container
delegates to StackManager), migrate (wraps manage migrate
--no-input), command surface (framework --help lists all three;
django --help lists all four subcommands).

Gates: pytest 1116 passed, ruff clean, mypy strict clean. No new
optional dependency extras.

Author: imanimanyara

CHANGELOG.md

@@ -6,6 +6,56 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [0.16.0] — 2026-05-16
+
+### Added
+
+- **`shimkit framework django`** — third framework recipe.
+  Modelled on Laravel + Symfony with Django-specific
+  conventions:
+  - `perms PATH [--group G]` (MODERATE) — fixes `media/` +
+    `staticfiles/` permissions.
+  - `env PATH [--name N] [--debug/--no-debug] [--db D]` (MODERATE)
+    — scaffolds `.env` with `SECRET_KEY` (Django's 50-char
+    alphabet) + `DATABASE_URL` (dj-database-url / django-environ
+    convention). Refuses to overwrite. Default DB is **postgres**
+    (Django's most common pairing); mysql + mariadb also
+    supported.
+  - `migrate PATH` — sugar for `manage migrate --no-input`.
+  - `manage -- <args>` — passthrough to `python manage.py`.
+    Host or `--in-container` via `shimkit stack lemp`.
+- `tools.framework.django` config block with `web_group`,
+  `file_mode`, `dir_mode`, `writable_dirs`, and `default_debug`.
+
+### Tests
+
+- 30 new tests in `tests/test_tools_framework_django.py` (1086 →
+  1116 total). _generate_secret_key (length / Django alphabet /
+  uniqueness across 100 calls), platform gating, perms (path
+  refusal / dry-run / media + staticfiles targeting / chgrp skip
+  on missing group / missing-writable warning / failed-step JSON),
+  env (overwrite refusal / SECRET_KEY shape + DATABASE_URL
+  postgres default / DEBUG True default / --no-debug flag /
+  DATABASE_URL mysql + mariadb / ALLOWED_HOSTS + EMAIL_BACKEND
+  present / Redis hint commented-out / dry-run no-write /
+  uniqueness across two scaffolds), manage (host happy path /
+  missing-python exits 69 / no-args refusal / missing-manage.py
+  refusal / --in-container delegates to StackManager), migrate
+  (wraps manage migrate --no-input), command surface (framework
+  --help lists django; django --help lists all four
+  subcommands).
+
+### Notes
+
+Third framework recipe. Same shape pattern as Laravel + Symfony:
+perms / env / passthrough + one framework-specific shortcut
+(`migrate` for Django, `cache-clear` for Symfony,
+`cron-install` for Laravel). No cron-install for Django —
+same reason as Symfony, no built-in scheduler.
+
+Gates: pytest 1116 passed, ruff clean, mypy strict clean. No new
+optional dependency extras.
+
 ## [0.15.0] — 2026-05-16
 
 ### Added

docs/README.md

@@ -61,6 +61,10 @@ shimkit is a collection. Each tool gets its own page:
 - **[`shimkit framework symfony`](tools/framework-symfony.md)** —
   Symfony helpers: perms (`var/`), `.env.local` scaffold with
   `APP_SECRET`, cache-clear, `bin/console` passthrough.
+- **[`shimkit framework django`](tools/framework-django.md)** —
+  Django helpers: perms (`media/` + `staticfiles/`), `.env`
+  scaffold with `SECRET_KEY` + django-environ-style
+  `DATABASE_URL`, migrate, `manage.py` passthrough.
 
 Top-level utilities (not tools):
 
@@ -94,6 +98,8 @@ Top-level utilities (not tools):
 
 Per-version, user-facing summaries (newest first):
 
+- **[`v0.16.0`](release-notes/v0.16.0.md)** — `shimkit framework
+  django` third framework recipe.
 - **[`v0.15.0`](release-notes/v0.15.0.md)** — `shimkit db redis`
   sixth engine. `Engine.up_command()` for argv-passed config.
 - **[`v0.14.0`](release-notes/v0.14.0.md)** — `shimkit framework

docs/release-notes/v0.16.0.md

@@ -0,0 +1,134 @@
+# shimkit 0.16.0
+
+`shimkit framework django` — third framework recipe under the
+existing `framework` parent. For the full machine-readable
+changelog, see [`CHANGELOG.md`](../../CHANGELOG.md).
+
+---
+
+## TL;DR
+
+```
+shimkit framework django perms PATH [--group G]               # MODERATE
+shimkit framework django env PATH [--name N] [--debug] [--db D] # MODERATE
+shimkit framework django migrate PATH
+shimkit framework django manage -- <args>
+```
+
+Same shape pattern as Laravel + Symfony. Adjusted for Django's
+conventions: writable `media/` + `staticfiles/`, `SECRET_KEY`
+(Django alphabet), `manage.py` (root-level), Python runtime.
+
+---
+
+## Differences across the three recipes
+
+| Aspect | Laravel | Symfony | Django |
+|--------|---------|---------|--------|
+| Writable tree | `storage/` + `bootstrap/cache/` | `var/` | `media/` + `staticfiles/` |
+| App secret | `APP_KEY=base64:...` | `APP_SECRET=...` (hex) | `SECRET_KEY=...` (50-char alphabet) |
+| Env file | `.env` | `.env.local` | `.env` (django-environ/decouple) |
+| Console | `artisan` | `bin/console` | `manage.py` |
+| Console runtime | `php` | `php` | `python` |
+| Scheduler shortcut | `cron-install` (every minute) | — | `migrate` (sugar for `manage migrate`) |
+
+---
+
+## `env` shape
+
+`.env` is the standard for django-environ / python-decouple
+projects. shimkit writes:
+
+```ini
+# Django local environment overrides.
+# Read by django-environ / python-decouple from .env at
+# project root. Production should override via real secrets
+# management.
+
+SECRET_KEY=<50 chars from Django's documented alphabet>
+DEBUG=True
+ALLOWED_HOSTS="localhost,127.0.0.1"
+
+DATABASE_URL="postgres://root:shimkit-dev@127.0.0.1:15432/<dirname>"
+
+# Cache + queue (pair with `shimkit db redis up`).
+# REDIS_URL="redis://default:shimkit-dev@127.0.0.1:16379/0"
+
+# Email — defaults to the console backend; override in prod.
+EMAIL_BACKEND=django.core.mail.backends.console.EmailBackend
+```
+
+`SECRET_KEY` matches what
+`django.core.management.utils.get_random_secret_key()` would
+emit — 50 chars from `[a-zA-Z0-9!@#$%^&*(-_=+)]`. shimkit doesn't
+depend on Django being installed to scaffold the file.
+
+Default DB is **postgres** (most-shipped pairing). Override:
+
+```bash
+shimkit framework django env --yes --db mysql ./my-app
+shimkit framework django env --yes --db mariadb ./my-app
+```
+
+The `# REDIS_URL=...` comment is a hint pointing at
+`shimkit db redis up` (v0.15.0). Uncomment to wire Redis.
+
+---
+
+## End-to-end example
+
+```bash
+# 1. Database + optional cache
+shimkit db postgres up
+shimkit db redis up
+
+# 2. Scaffold env + fix perms
+shimkit framework django env  --yes --db postgres ./my-app
+shimkit framework django perms --yes ./my-app
+
+# 3. Migrate + superuser
+shimkit framework django migrate ./my-app
+shimkit framework django manage --project ./my-app -- createsuperuser
+
+# 4. Dev server
+shimkit framework django manage --project ./my-app -- runserver
+```
+
+---
+
+## Why no `cron-install`
+
+Same reason as Symfony (v0.14.0): Django doesn't ship a built-in
+scheduler analogous to Laravel's `schedule:run`. Application-
+specific cron entries go via `shimkit cron add` directly:
+
+```bash
+shimkit cron add --yes \
+    --name django-nightly \
+    --schedule "0 3 * * *" \
+    --cmd "cd /var/www/my-app && python manage.py my-nightly-job >> /dev/null 2>&1"
+```
+
+Django-Q / Celery / huey are the in-process alternatives — shimkit
+doesn't bind to any one of them.
+
+---
+
+## Stats
+
+- Tests: 1086 → 1116 (+30)
+- Gates: pytest, ruff, mypy strict — all green
+- New optional extras: 0
+
+---
+
+## Upgrading
+
+```bash
+uv tool upgrade shimkit
+pipx upgrade shimkit
+```
+
+Laravel + Symfony users see no behavioural change. To start
+using the Django recipe, just invoke
+`shimkit framework django --help`.

docs/tools/framework-django.md

@@ -0,0 +1,167 @@
+# shimkit framework django
+
+Django-specific helpers. Third recipe under the `framework`
+parent. Same shape as the Laravel + Symfony recipes; adjusted
+for Django's conventions.
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `shimkit framework django`                                  | Menu. |
+| `shimkit framework django perms PATH [--group G]`           | MODERATE. Fix `media/` + `staticfiles/` permissions. |
+| `shimkit framework django env PATH [--name N] [--debug/--no-debug] [--db D]` | MODERATE. Scaffold `.env` with `SECRET_KEY` + `DATABASE_URL`. |
+| `shimkit framework django migrate PATH`                     | Wraps `python manage.py migrate --no-input`. |
+| `shimkit framework django manage -- <args>`                 | Passthrough to `python manage.py`. |
+
+Universal flags before the subcommand (`--quiet`, `--verbose`,
+`--log-file`, `--no-color`, `--color`, `--no-input`); per-command
+flags after (`--json`, `--dry-run`, `--yes`, `--force`).
+
+## Differences from Laravel + Symfony
+
+| Aspect | Laravel | Symfony | Django |
+|--------|---------|---------|--------|
+| Writable tree | `storage/` + `bootstrap/cache/` | `var/` | `media/` + `staticfiles/` |
+| App secret | `APP_KEY=base64:...` | `APP_SECRET=...` (hex) | `SECRET_KEY=...` (Django alphabet) |
+| Env file | `.env` (gitignored) | `.env.local` (gitignored) | `.env` (django-environ / decouple convention) |
+| Console | `artisan` (root) | `bin/console` | `manage.py` (root) |
+| Console runtime | `php` | `php` | `python` |
+| Scheduler | `schedule:run` every minute | none — use `shimkit cron add` | none — use `shimkit cron add` |
+
+## perms
+
+`media/` (user uploads) and `staticfiles/` (collectstatic target)
+are the canonical writable trees in modern Django layouts.
+`staticfiles/` typically doesn't exist on a fresh project until
+the first `collectstatic` — shimkit warns about that and runs
+the global `chmod` passes regardless.
+
+Group detection: `getent group <name>` on Linux, `dscl . -read
+/Groups/<name>` on macOS, `grp.getgrnam()` Python fallback.
+
+```bash
+shimkit framework django perms --yes ./my-django-app
+shimkit framework django perms --yes --group staff ./my-django-app  # macOS
+shimkit framework django perms --dry-run ./my-django-app
+```
+
+## env
+
+Writes `.env` with a generated `SECRET_KEY` + `DATABASE_URL` +
+sensible dev defaults. **Refuses to overwrite** an existing
+`.env`. The format is django-environ / python-decouple
+compatible: `KEY=value` lines. `DATABASE_URL` follows the
+Heroku / dj-database-url convention.
+
+`SECRET_KEY` is 50 chars from Django's documented alphabet —
+matches what `django.core.management.utils.get_random_secret_key()`
+would emit, but shimkit doesn't depend on Django being installed
+to scaffold the file.
+
+Default DB engine is **postgres** (Django's most-shipped pairing).
+Override with `--db mysql` or `--db mariadb`.
+
+| `--db`     | URL prefix | Port |
+|------------|------------|------|
+| `postgres` (default) | `postgres://` | 15432 |
+| `mysql`    | `mysql://`    | 13306 |
+| `mariadb`  | `mysql://`    | 13307 |
+
+```bash
+shimkit db postgres up
+shimkit framework django env --yes --db postgres ./my-app
+
+# DEBUG=False for a more prod-like local
+shimkit framework django env --yes --no-debug ./my-app
+```
+
+The env file also lists a commented-out `REDIS_URL` line as a
+hint pointing the user at `shimkit db redis up` (v0.15.0+).
+
+## migrate
+
+Sugar for `manage migrate --no-input`:
+
+```bash
+shimkit framework django migrate ./my-app
+shimkit framework django migrate --in-container --stack myapp ./my-app
+```
+
+## manage
+
+Generic passthrough to `python manage.py`. Host execution by
+default — preflights `python` via
+`shimkit.core.version.preflight`, exits 69 with the remediation
+hint when `python` is missing. `--in-container` routes through
+`shimkit stack lemp`'s php-fpm container (which has `python`
+installed via the upstream PHP-FPM image's base layers).
+
+```bash
+shimkit framework django manage --project ./my-app -- runserver 0.0.0.0:8000
+shimkit framework django manage --project ./my-app -- createsuperuser
+shimkit framework django manage --project ./my-app -- collectstatic --no-input
+```
+
+`--project` defaults to the current working directory.
+
+## End-to-end example
+
+```bash
+# 1. Database
+shimkit db postgres up
+
+# 2. Optional: Redis cache / Channels
+shimkit db redis up
+
+# 3. Scaffold env + fix perms
+shimkit framework django env  --yes --db postgres ./my-app
+shimkit framework django perms --yes ./my-app
+
+# 4. Migrate + create superuser
+shimkit framework django migrate ./my-app
+shimkit framework django manage --project ./my-app -- createsuperuser
+
+# 5. Run the dev server
+shimkit framework django manage --project ./my-app -- runserver
+```
+
+## Configuration
+
+```json
+{
+  "tools": {
+    "framework": {
+      "django": {
+        "web_group": "www-data",
+        "file_mode": "664",
+        "dir_mode": "775",
+        "writable_dirs": ["media", "staticfiles"],
+        "default_debug": true
+      }
+    }
+  }
+}
+```
+
+Override `web_group` per host. Add `writable_dirs` entries if
+your app writes outside `media/` + `staticfiles/`.
+
+## Exit codes
+
+| Code | Meaning |
+|-----:|---------|
+| 0    | success |
+| 1    | bad path, missing `manage.py`, refusing overwrite, prompt cancelled |
+| 2    | Typer usage error |
+| 69   | `EX_UNAVAILABLE` — wrong platform or missing `python` for `manage`/`migrate` |
+| 130  | SIGINT |
+
+## Platform support
+
+| Platform | Status |
+|----------|--------|
+| macOS    | full. Dev account typically owns the project, so `chgrp` is no-op'd unless `--group` is passed. |
+| Linux    | full. Targets `www-data` by default; override with `--group`. |
+| WSL      | works (Linux path). |
+| Windows  | out of charter (use WSL). |

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "shimkit"
-version = "0.15.0"
+version = "0.16.0"
 description = "A toolkit of developer utilities — Java version manager, shell upgrader, and more. Python tools, shimmed by bash."
 readme = "README.md"
 license = { file = "LICENSE" }

src/shimkit/__init__.py

@@ -3,5 +3,5 @@
 Python tools, shimmed by bash.
 """
 
-__version__ = "0.15.0"
+__version__ = "0.16.0"
 __all__ = ["__version__"]