@django-stack/cli 0.8.1 → 0.10.0

package/dist/index.d.ts

@@ -158,7 +158,7 @@ export declare const STACK_OPTIONS: readonly [{
     readonly value: "on";
     readonly label: "On";
     readonly hint: "in the admin and by email";
-    readonly generated: false;
+    readonly generated: true;
   }, {
     readonly value: "off";
     readonly label: "Off";
@@ -174,7 +174,7 @@ export declare const STACK_OPTIONS: readonly [{
     readonly value: "on";
     readonly label: "On";
     readonly hint: "proof of work, no tracking";
-    readonly generated: false;
+    readonly generated: true;
   }, {
     readonly value: "off";
     readonly label: "Off";
@@ -206,7 +206,8 @@ export declare const STACK_OPTIONS: readonly [{
   readonly values: readonly [{
     readonly value: "pnpm";
     readonly label: "pnpm";
-    readonly generated: false;
+    readonly hint: "with a day's delay on new releases";
+    readonly generated: true;
   }, {
     readonly value: "npm";
     readonly label: "npm";
@@ -214,7 +215,8 @@ export declare const STACK_OPTIONS: readonly [{
   }, {
     readonly value: "bun";
     readonly label: "Bun";
-    readonly generated: false;
+    readonly hint: "for installs; the frontend runs on Node.js";
+    readonly generated: true;
   }];
 }, {
   readonly key: "media";
@@ -233,6 +235,28 @@ export declare const STACK_OPTIONS: readonly [{
     readonly hint: "any S3-compatible service; credentials later";
     readonly generated: true;
   }];
+}, {
+  readonly key: "errors";
+  readonly flag: "--errors";
+  readonly message: "Error reports";
+  readonly description: "How you hear about errors in production";
+  readonly bits: 2;
+  readonly values: readonly [{
+    readonly value: "email";
+    readonly label: "Email";
+    readonly hint: "to the superusers, and in the admin";
+    readonly generated: true;
+  }, {
+    readonly value: "sentry";
+    readonly label: "Sentry";
+    readonly hint: "sentry.io, with SENTRY_DSN";
+    readonly generated: true;
+  }, {
+    readonly value: "off";
+    readonly label: "Off";
+    readonly hint: "the logs only";
+    readonly generated: true;
+  }];
 }];
 type Options = (typeof STACK_OPTIONS)[number];
 type StackKey = Options["key"];
@@ -272,6 +296,14 @@ interface ScaffoldOptions {
   localS3?: boolean;
   /** Page analytics with the bundled Umami (the `analytics` profile). */
   analytics?: boolean;
+  /** Content Studio's notifications app; on by default. */
+  notifications?: boolean;
+  /** The captcha of the contact form; on by default. */
+  captcha?: boolean;
+  /** The frontend's package manager; pnpm by default. */
+  packageManager?: PackageManager;
+  /** How errors are reported in production; by email by default. */
+  errors?: Stack["errors"];
   /** The cache backend; the database by default. */
   cache?: Stack["cache"];
   /** The task queue; Huey where the cache is by default. */
@@ -287,6 +319,8 @@ interface ScaffoldOptions {
   /** Where the templates are; the ones in the package by default. */
   templatesDir?: string;
 }
+/** A package manager of the frontend. */
+type PackageManager = Stack["packageManager"];
 interface ScaffoldResult {
   directory: string;
   adminUsername: string;
@@ -295,6 +329,11 @@ interface ScaffoldResult {
 }
 /** The `.env` values of a cache and a task queue: CACHE_URL, TASKS_URL and TASK_WORKERS. */
 export declare function cacheEnv(stack: Pick<Stack, "cache" | "tasks">): Record<string, string>;
+/**
+ * Adds or removes Content Studio's notifications app in the text of
+ * `backend/config/settings.py`. Throws when it can't find where it goes.
+ */
+export declare function setNotificationsApp(settingsText: string, on: boolean): string;
 /** Whether `.env` values use the Valkey service (the `valkey` profile). */
 export declare function usesValkey(env: Record<string, string | undefined>): boolean;
 /** A valid project name from a directory name: `My Site` becomes `my-site`. */

package/dist/index.js

@@ -1 +1 @@
-export { P as DEFAULT_STACK, i as FRONTENDS, F as NAMED_PRESETS, L as STACK_OPTIONS, v as VERSION, o as cacheEnv, z as decodePreset, B as encodePreset, b as generateProjectSecrets, x as generateSecret, l as normalizeDatabaseUrl, et as parseEnv, V as pendingChoices, n as productionEnv, H as resolvePreset, Y as runDoctor, d as scaffold, nt as setEnvValues, p as toProjectName, h as usesValkey, r as validateDomain, g as validateProjectName } from "./production-CGkI7oNe.js";
+export { z as DEFAULT_STACK, i as FRONTENDS, B as NAMED_PRESETS, U as STACK_OPTIONS, S as VERSION, o as cacheEnv, G as decodePreset, K as encodePreset, w as generateProjectSecrets, T as generateSecret, d as normalizeDatabaseUrl, ot as parseEnv, q as pendingChoices, n as productionEnv, J as resolvePreset, tt as runDoctor, p as scaffold, ct as setEnvValues, m as setNotificationsApp, g as toProjectName, y as usesValkey, r as validateDomain, b as validateProjectName } from "./production-Ct_qoeXk.js";

package/dist/{production-CGkI7oNe.js → production-Ct_qoeXk.js}

@@ -582,7 +582,7 @@ const STACK_OPTIONS = [
 			value: "on",
 			label: "On",
 			hint: "in the admin and by email",
-			generated: false
+			generated: true
 		}, {
 			value: "off",
 			label: "Off",
@@ -599,7 +599,7 @@ const STACK_OPTIONS = [
 			value: "on",
 			label: "On",
 			hint: "proof of work, no tracking",
-			generated: false
+			generated: true
 		}, {
 			value: "off",
 			label: "Off",
@@ -634,7 +634,8 @@ const STACK_OPTIONS = [
 			{
 				value: "pnpm",
 				label: "pnpm",
-				generated: false
+				hint: "with a day's delay on new releases",
+				generated: true
 			},
 			{
 				value: "npm",
@@ -644,7 +645,8 @@ const STACK_OPTIONS = [
 			{
 				value: "bun",
 				label: "Bun",
-				generated: false
+				hint: "for installs; the frontend runs on Node.js",
+				generated: true
 			}
 		]
 	},
@@ -665,6 +667,33 @@ const STACK_OPTIONS = [
 			hint: "any S3-compatible service; credentials later",
 			generated: true
 		}]
+	},
+	{
+		key: "errors",
+		flag: "--errors",
+		message: "Error reports",
+		description: "How you hear about errors in production",
+		bits: 2,
+		values: [
+			{
+				value: "email",
+				label: "Email",
+				hint: "to the superusers, and in the admin",
+				generated: true
+			},
+			{
+				value: "sentry",
+				label: "Sentry",
+				hint: "sentry.io, with SENTRY_DSN",
+				generated: true
+			},
+			{
+				value: "off",
+				label: "Off",
+				hint: "the logs only",
+				generated: true
+			}
+		]
 	}
 ];
 /**
@@ -945,7 +974,9 @@ function projectManifest(project) {
 function projectStack(project) {
 	const fromEnv = {
 		analytics: project.profiles.includes("analytics") ? "umami" : "off",
-		...project.env.CACHE_URL === void 0 ? {} : cacheStack(project.env)
+		...project.env.CACHE_URL === void 0 ? {} : cacheStack(project.env),
+		...notificationsStack(project),
+		...captchaStack(project)
 	};
 	const { preset } = projectManifest(project);
 	if (preset) try {
@@ -960,6 +991,23 @@ function projectStack(project) {
 		storage: project.profiles.includes("s3") ? "s3" : "local"
 	};
 }
+/** Notifications are on when the backend's INSTALLED_APPS has Content Studio's notifications app. */
+function notificationsStack(project) {
+	const settings = join(project.directory, "backend", "config", "settings.py");
+	if (!existsSync(settings)) return {};
+	return { notifications: /^ *["']content_studio\.notifications["'],/m.test(readFileSync(settings, "utf8")) ? "on" : "off" };
+}
+/** The line of DjangoStack's captcha app in the backend's INSTALLED_APPS. */
+const CAPTCHA_APP = /^ *["']django_stack\.contrib\.captcha["'],/m;
+/**
+* The captcha is on when the backend has DjangoStack's captcha app and
+* CAPTCHA is not off. Projects from before the captcha have no app.
+*/
+function captchaStack(project) {
+	const settings = join(project.directory, "backend", "config", "settings.py");
+	if (!existsSync(settings)) return {};
+	return { captcha: CAPTCHA_APP.test(readFileSync(settings, "utf8")) && project.env.CAPTCHA !== "off" ? "on" : "off" };
+}
 const REDIS = /^(redis|rediss|valkey|valkeys):/;
 /**
 * The cache and the tasks a project's `.env` runs. Projects from before 0.7
@@ -1113,6 +1161,56 @@ const PACKAGE_NAME = "@django-stack/cli";
 // src/scaffold.ts
 /** The frontends this version of the CLI generates. */
 const FRONTENDS = stackOption("frontend").values.filter((value) => value.generated).map((value) => value.value);
+/** The pnpm and Bun versions the frontend image installs with. */
+const PNPM_VERSION = "12.18.0";
+const BUN_VERSION = "1.4.4";
+const LOCKFILES = {
+	pnpm: "pnpm-lock.yaml",
+	npm: "package-lock.json",
+	bun: "bun.lock"
+};
+/** The install command of a package manager: frozen to the lockfile when there is one. */
+function installCommand(manager, flags = "") {
+	const frozen = manager === "npm" ? "npm ci" : `${manager} install --frozen-lockfile`;
+	return `if [ -f ${LOCKFILES[manager]} ]; then ${frozen}${flags}; else ${manager} install${flags}; fi`;
+}
+/**
+* The template values for a package manager: the commands in the README and
+* AGENTS.md, and the install steps of the frontend's Dockerfile. Scripts run
+* with npm in the image whatever installed them; it comes with Node.js.
+*/
+function packageManagerValues(manager) {
+	return {
+		package_manager: manager,
+		pm_run: {
+			pnpm: "pnpm",
+			npm: "npm run",
+			bun: "bun run"
+		}[manager],
+		pm_backend: {
+			pnpm: "pnpm backend",
+			npm: "npm run backend --",
+			bun: "bun run backend"
+		}[manager],
+		pm_setup: {
+			pnpm: `RUN npm install --global pnpm@${PNPM_VERSION}`,
+			npm: "# npm comes with Node.js.",
+			bun: `COPY --from=oven/bun:${BUN_VERSION}-alpine /usr/local/bin/bun /usr/local/bin/bun`
+		}[manager],
+		pm_manifests: {
+			pnpm: "package.json pnpm-lock.yaml* pnpm-workspace.yaml",
+			npm: "package.json package-lock.json*",
+			bun: "package.json bun.lock*"
+		}[manager],
+		pm_install: installCommand(manager),
+		pm_install_no_scripts: installCommand(manager, " --ignore-scripts"),
+		pm_prune: {
+			pnpm: "pnpm prune --prod",
+			npm: "npm prune --omit=dev",
+			bun: "rm -rf node_modules && bun install --production"
+		}[manager]
+	};
+}
 /** Umami's database URL: the project's database, with Umami's tables in the `umami` schema. */
 function umamiDatabaseUrl(databaseUrl) {
 	const url = new URL(databaseUrl);
@@ -1155,6 +1253,25 @@ function cacheEnv(stack) {
 		...TASK_ENV[taskQueue(stack)]
 	};
 }
+/** The line of Content Studio's notifications app in the backend's INSTALLED_APPS. */
+const NOTIFICATIONS_APP = "    \"content_studio.notifications\",  # notifications in the admin and by email\n";
+const NOTIFICATIONS_PATTERN = /^ *["']content_studio\.notifications["'],.*\n/m;
+/**
+* Adds or removes Content Studio's notifications app in the text of
+* `backend/config/settings.py`. Throws when it can't find where it goes.
+*/
+function setNotificationsApp(settingsText, on) {
+	const present = NOTIFICATIONS_PATTERN.test(settingsText);
+	if (!on) return settingsText.replace(NOTIFICATIONS_PATTERN, "");
+	if (present) return settingsText;
+	const after = [
+		/^ *["']content_studio\.contrib\.password_reset["'],.*\n/m,
+		/^ *["']content_studio\.media_library["'],.*\n/m,
+		/^ *["']content_studio["'],.*\n/m
+	].find((pattern) => pattern.test(settingsText));
+	if (!after) throw new Error("backend/config/settings.py has no \"content_studio\" in INSTALLED_APPS; add \"content_studio.notifications\" there yourself.");
+	return settingsText.replace(after, (line) => line + NOTIFICATIONS_APP);
+}
 /** Whether `.env` values use the Valkey service (the `valkey` profile). */
 function usesValkey(env) {
 	return [env.CACHE_URL, env.TASKS_URL].some((url) => /^(redis|rediss|valkey|valkeys):\/\/cache[:/]/.test(url ?? ""));
@@ -1238,6 +1355,7 @@ function scaffold(options) {
 	const about = join(target, "frontend", "template.json");
 	const frontend = JSON.parse(readFileSync(about, "utf8"));
 	rmSync(about);
+	const packageManager = options.packageManager ?? "pnpm";
 	const values = {
 		project_name: options.name,
 		frontend: options.frontend,
@@ -1247,7 +1365,8 @@ function scaffold(options) {
 		cli_version: CLI_VERSION,
 		preset: options.preset ?? encodePreset(DEFAULT_STACK),
 		site_port: String(options.ports?.SITE_PORT ?? 3e3),
-		mail_port: String(options.ports?.MAIL_PORT ?? 8025)
+		mail_port: String(options.ports?.MAIL_PORT ?? 8025),
+		...packageManagerValues(packageManager)
 	};
 	const files = walk(target);
 	for (const file of files) {
@@ -1256,6 +1375,20 @@ function scaffold(options) {
 		const rendered = render(text, values);
 		if (rendered !== text) writeFileSync(file, rendered);
 	}
+	if (packageManager !== "pnpm") rmSync(join(target, "frontend", "pnpm-workspace.yaml"), { force: true });
+	if (packageManager !== "npm") {
+		const packageJson = join(target, "frontend", "package.json");
+		const manifest = JSON.parse(readFileSync(packageJson, "utf8"));
+		const version = packageManager === "pnpm" ? PNPM_VERSION : BUN_VERSION;
+		writeFileSync(packageJson, `${JSON.stringify({
+			...manifest,
+			packageManager: `${packageManager}@${version}`
+		}, null, 2)}\n`);
+	}
+	if (options.notifications === false) {
+		const settings = join(target, "backend", "config", "settings.py");
+		writeFileSync(settings, setNotificationsApp(readFileSync(settings, "utf8"), false));
+	}
 	if (options.timeZone && options.timeZone !== "UTC") {
 		const settings = join(target, "backend", "config", "settings.py");
 		const text = readFileSync(settings, "utf8");
@@ -1285,6 +1418,8 @@ function scaffold(options) {
 	env = setEnvValues(env, { COMPOSE_PROFILES: profiles.join(",") });
 	if (options.ports) env = setEnvValues(env, portValues(parseEnv(env), options.ports));
 	if (!options.demoContent) env = setEnvValues(env, { SEED_DEMO_CONTENT: "0" });
+	if (options.errors && options.errors !== "email") env = setEnvValues(env, { ERRORS: options.errors });
+	if (options.captcha === false) env = setEnvValues(env, { CAPTCHA: "off" });
 	writeFileSync(join(target, ".env"), env, { mode: 384 });
 	writeFileSync(join(target, ".env.example"), envExample);
 	rmSync(join(target, "env.example"));
@@ -1349,6 +1484,74 @@ function linkPackages(target, monorepo) {
 	writeFileSync(packageJson, `${JSON.stringify(manifest, null, 2)}\n`);
 }
 /** Locks the backend's dependencies with uv, when uv is installed. */
+/** Runs a package manager in the frontend directory: pnpm and Bun through npx, at the image's version. */
+function runPackageManager(directory, manager, args) {
+	const [file, commandArgs] = manager === "npm" ? ["npm", args] : ["npx", [
+		"--yes",
+		`${manager}@${manager === "pnpm" ? PNPM_VERSION : BUN_VERSION}`,
+		...args
+	]];
+	try {
+		execFileSync(file, commandArgs, {
+			cwd: directory,
+			stdio: "ignore",
+			shell: process.platform === "win32"
+		});
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** Writes the frontend's lockfile with the chosen package manager, without installing anything. */
+function lockFrontend(target, manager) {
+	const directory = join(target, "frontend");
+	return runPackageManager(directory, manager, manager === "npm" ? [
+		"install",
+		"--package-lock-only",
+		"--ignore-scripts",
+		"--no-audit",
+		"--no-fund"
+	] : ["install", "--lockfile-only"]) && existsSync(join(directory, LOCKFILES[manager]));
+}
+/** The package manager of a project's frontend, from its lockfile. */
+function frontendPackageManager(directory) {
+	return Object.keys(LOCKFILES).find((manager) => existsSync(join(directory, "frontend", LOCKFILES[manager])));
+}
+/**
+* Updates the frontend's lockfile, without installing: the @django-stack
+* packages, or every package with `all`, within the ranges of package.json.
+* Returns the lockfile, or undefined without one or on failure.
+*/
+function updateFrontendLock(target, all = false) {
+	const manager = frontendPackageManager(target);
+	if (!manager) return void 0;
+	const directory = join(target, "frontend");
+	const manifest = JSON.parse(readFileSync(join(directory, "package.json"), "utf8"));
+	const names = Object.keys(manifest.dependencies ?? {}).filter((name) => name.startsWith("@django-stack/"));
+	const packages = all ? [] : names;
+	const args = {
+		pnpm: [
+			"update",
+			...packages,
+			"--lockfile-only"
+		],
+		npm: [
+			"update",
+			...packages,
+			"--package-lock-only",
+			"--ignore-scripts",
+			"--no-audit",
+			"--no-fund"
+		],
+		bun: [
+			"update",
+			...packages,
+			"--lockfile-only"
+		]
+	}[manager];
+	if (!all && !names.length) return LOCKFILES[manager];
+	return runPackageManager(directory, manager, args) ? LOCKFILES[manager] : void 0;
+}
 function lockBackend(target) {
 	try {
 		execFileSync("uv", ["lock", "--quiet"], {
@@ -1441,4 +1644,4 @@ function productionEnv(devEnv, options) {
 		todo
 	};
 }
-export { isDockerDown as $, projectUrls as A, encodePreset as B, RUN_ENV as C, findProjectDirectory as D, composeOutput as E, NAMED_PRESETS as F, chooseFreePorts as G, resolvePreset as H, PROMPT_ORDER as I, portValues as J, describeMove as K, STACK_OPTIONS as L, readProject as M, runningServices as N, parseProfiles as O, DEFAULT_STACK as P, dockerRunning as Q, applies as R, RUN_DOMAIN as S, compose as T, stackOption as U, pendingChoices as V, DEV_PORTS as W, checkTools as X, runDoctor as Y, dockerNotRunning as Z, validateTimeZone as _, LOCAL_S3 as a, generateProjectSecrets as b, lockBackend as c, scaffold as d, parseEnv as et, timeZones as f, validateProjectName as g, usesValkey as h, FRONTENDS as i, readLocalRun as j, projectStack as k, normalizeDatabaseUrl as l, umamiEnv as m, productionEnv as n, setEnvValues as nt, cacheEnv as o, toProjectName as p, envPorts as q, validateDomain as r, localS3 as s, missingS3 as t, quoteEnvValue as tt, relativeDirectory as u, CLI_VERSION as v, activeProject as w, generateSecret as x, PACKAGE_NAME as y, decodePreset as z };
+export { envPorts as $, compose as A, NAMED_PRESETS as B, PACKAGE_NAME as C, RUN_DOMAIN as D, CAPTCHA_APP as E, projectUrls as F, decodePreset as G, PROMPT_ORDER as H, readLocalRun as I, resolvePreset as J, encodePreset as K, readProject as L, findProjectDirectory as M, parseProfiles as N, RUN_ENV as O, projectStack as P, describeMove as Q, runningServices as R, CLI_VERSION as S, generateSecret as T, STACK_OPTIONS as U, NODE_FRONTENDS as V, applies as W, DEV_PORTS as X, stackOption as Y, chooseFreePorts as Z, umamiEnv as _, LOCAL_S3 as a, isDockerDown as at, validateProjectName as b, localS3 as c, setEnvValues as ct, normalizeDatabaseUrl as d, portValues as et, relativeDirectory as f, toProjectName as g, timeZones as h, FRONTENDS as i, dockerRunning as it, composeOutput as j, activeProject as k, lockBackend as l, setNotificationsApp as m, productionEnv as n, checkTools as nt, cacheEnv as o, parseEnv as ot, scaffold as p, pendingChoices as q, validateDomain as r, dockerNotRunning as rt, frontendPackageManager as s, quoteEnvValue as st, missingS3 as t, runDoctor as tt, lockFrontend as u, updateFrontendLock as v, generateProjectSecrets as w, validateTimeZone as x, usesValkey as y, DEFAULT_STACK as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@django-stack/cli",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "description": "The production-ready Django, batteries included stack. Create and manage DjangoStack projects: a Django backend, a frontend, Postgres and Docker Compose in one command.",
   "license": "MIT",
   "author": "Leon van der Grient",

package/templates/backend/Dockerfile

@@ -20,16 +20,15 @@ WORKDIR /app
 FROM base AS deps
 COPY pyproject.toml uv.lock* ./
 COPY vendor/ vendor/
-RUN --mount=type=cache,target=/root/.cache/uv \
-    uv sync --no-dev --no-install-project
+# No BuildKit cache mounts: Railway rejects them, and the layer is cached anyway.
+RUN uv sync --no-dev --no-install-project --no-cache
 
 # Development runs as root, so files the container writes into the mounted
 # source (such as new migrations) work on every host. Production does not.
 # The entrypoint runs with sh, so it works without the executable bit (the
 # mounted source keeps the host's file modes).
 FROM deps AS dev
-RUN --mount=type=cache,target=/root/.cache/uv \
-    uv sync --no-install-project
+RUN uv sync --no-install-project --no-cache
 ENTRYPOINT ["sh", "/app/entrypoint.sh"]
 CMD ["python", "manage.py", "runserver", "0.0.0.0:8000"]
 
@@ -44,4 +43,4 @@ EXPOSE 8000
 HEALTHCHECK --interval=10s --timeout=5s --start-period=30s --retries=5 \
     CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/readyz', timeout=4)"
 ENTRYPOINT ["sh", "/app/entrypoint.sh"]
-CMD ["gunicorn", "config.asgi:application", "--worker-class", "uvicorn_worker.UvicornWorker", "--bind", "0.0.0.0:8000", "--workers", "3", "--access-logfile", "-", "--no-control-socket"]
+CMD ["gunicorn", "config.asgi:application", "--worker-class", "uvicorn_worker.UvicornWorker", "--bind", "0.0.0.0:8000", "--workers", "3", "--no-control-socket"]

package/templates/backend/config/settings.py

@@ -38,13 +38,16 @@ INSTALLED_APPS = [
     "content_studio",
     "content_studio.media_library",
     "content_studio.contrib.password_reset",
+    "content_studio.notifications",  # notifications in the admin and by email
     "django_stack",
+    "django_stack.contrib.captcha",  # the captcha of the contact form (CAPTCHA=off turns it off)
     "content",
     # Last: builds the API routes once every model is exposed.
     "headless.rest",
 ]
 
 MIDDLEWARE = [
+    "django_stack.logs.RequestIdMiddleware",  # request IDs and the access log
     "django.middleware.security.SecurityMiddleware",
     "whitenoise.middleware.WhiteNoiseMiddleware",
     "django.contrib.sessions.middleware.SessionMiddleware",

package/templates/backend/config/studio.py

@@ -10,12 +10,16 @@ from content_studio.contrib.huey import HueyAdapter
 from content_studio.dashboard.tasks import TaskDashboard
 from content_studio.extensions import UserMenuLink
 from django_stack.analytics import UmamiProvider
+from django_stack.studio import SystemLink, SystemPage
 
 
 class SiteStudio(ContentStudioSite):
     extensions = [
         TaskDashboard(adapter=HueyAdapter()),
         UserMenuLink(url="/tasks/", label="Tasks", icon="ph-bold ph-queue"),
+        # Superusers only: the health checks and the latest error reports.
+        SystemPage(),
+        SystemLink(),
     ]
 
     # Page analytics from the bundled Umami when UMAMI_URL is set (see

package/templates/backend/content/apps.py

@@ -1,6 +1,10 @@
-from django.apps import AppConfig
+from django.apps import AppConfig, apps
 
 
 class ContentConfig(AppConfig):
     name = "content"
     verbose_name = "Content"
+
+    def ready(self):
+        if apps.is_installed("content_studio.notifications"):
+            from . import notifications  # noqa: F401 - registers the events

package/templates/backend/content/models.py

@@ -5,8 +5,8 @@ site settings, menus, redirects and form submissions.
 These models are yours: add fields, remove models, create new ones. Every
 model exposed with ``@expose()`` gets routes under /api/ (see
 https://djangoheadless.org/docs/models); register it in ``admin.py`` to edit
-it in Content Studio. After a change, run ``pnpm backend makemigrations``
-and ``pnpm generate:types``.
+it in Content Studio. After a change, run ``{{pm_run}} backend makemigrations``
+and ``{{pm_run}} generate:types``.
 """
 
 from content_studio.blocks import Block, BlockField

package/templates/backend/content/notifications.py

@@ -0,0 +1,36 @@
+"""
+The notifications of the site, with Content Studio's notifications app
+(`content_studio.notifications` in INSTALLED_APPS). Editors get them in
+the admin and, when they leave them unread, in an email digest. Each
+editor picks which events they get on their settings page.
+
+Register your own events here, and send them with notify(); see
+https://djangocontentstudio.org for the API.
+"""
+
+from content_studio.notifications import notify, register_event
+from django.db.models.signals import post_save
+from django.dispatch import receiver
+from django.utils.translation import gettext_lazy as _
+
+from .models import FormSubmission
+
+FORM_SUBMITTED = register_event(
+    "site.form_submitted",
+    _("Contact form messages"),
+    _("A visitor sent a message with the contact form."),
+)
+
+
+@receiver(post_save, sender=FormSubmission, dispatch_uid="content_form_submitted")
+def notify_form_submitted(sender, instance, created, raw=False, **kwargs):
+    """Every editor who may read the messages hears about a new one."""
+    if created and not raw:
+        notify(
+            FORM_SUBMITTED.key,
+            title=_("Message from %(name)s"),
+            # The visitor's text goes in params: a "%" in it stays text.
+            body=_("%(message)s"),
+            params={"name": instance.name, "message": instance.message[:200]},
+            target=instance,
+        )

package/templates/backend/content/tests/test_api.py

@@ -1,11 +1,13 @@
 """
 Smoke tests of the content API: every exposed model answers the read-only
 key, drafts stay hidden, and the contact form takes submissions.
-Run them with `pnpm test` at the project root.
+Run them with `{{pm_run}} test` at the project root.
 """
 
 import pytest
+from django.apps import apps
 from django.conf import settings
+from django_stack.contrib.captcha.testing import captcha_token
 from rest_framework.test import APIClient
 
 from content.models import FormSubmission, Page, Post
@@ -62,12 +64,40 @@ def test_post_by_slug(reader, seeded):
 def test_contact_form(seeded):
     response = APIClient().post(
         "/api/content.formsubmission",
-        {"name": "Ada", "email": "ada@example.com", "message": "Hello"},
+        {"name": "Ada", "email": "ada@example.com", "message": "Hello", "captcha": captcha_token()},
         format="json",
     )
     assert response.status_code == 201
     assert FormSubmission.objects.filter(email="ada@example.com").exists()
 
 
+@pytest.mark.skipif(not settings.DJANGO_STACK["CAPTCHA"], reason="the captcha is off")
+def test_contact_form_needs_a_captcha(seeded):
+    response = APIClient().post(
+        "/api/content.formsubmission",
+        {"name": "Ada", "email": "ada@example.com", "message": "Hello"},
+        format="json",
+    )
+    assert response.status_code == 400
+    assert "captcha" in response.json()
+
+
+@pytest.mark.skipif(not apps.is_installed("content_studio.notifications"), reason="notifications are off")
+def test_contact_form_notifies_the_editors(seeded, django_capture_on_commit_callbacks):
+    from content_studio.notifications.models import Notification
+    from django.contrib.auth import get_user_model
+
+    editor = get_user_model().objects.create_superuser("editor", "editor@example.com", "x")
+    with django_capture_on_commit_callbacks(execute=True):
+        APIClient().post(
+            "/api/content.formsubmission",
+            {"name": "Ada", "email": "ada@example.com", "message": "100% sure", "captcha": captcha_token()},
+            format="json",
+        )
+    notification = Notification.objects.get(recipient=editor, event="site.form_submitted")
+    assert notification.get_title() == "Message from Ada"
+    assert notification.get_body() == "100% sure"
+
+
 def test_read_key_cannot_read_submissions(reader):
     assert reader.get("/api/content.formsubmission").status_code == 403

package/templates/backend/pyproject.toml

@@ -5,7 +5,7 @@ description = "The Django backend of {{project_name}}."
 requires-python = ">=3.12"
 dependencies = [
     "Django>=6.1,<6.2",
-    "django-stack[server,s3]>=0.8.1",
+    "django-stack[server,s3]>=0.10.0",
     "django-headless[schema]>=1.1.1",
     "django-content-studio[images,huey]>=1.11.0",
 ]

package/templates/base/AGENTS.md

@@ -17,7 +17,7 @@ backend/                 Django project
   content/seed.py        demo content
   content/tests/         pytest tests of the API
 frontend/                the {{frontend_label}} site; frontend/AGENTS.md lists its files
-  src/lib/headless.ts    generated API types; do not edit, run `npm run generate:types`
+  src/lib/headless.ts    generated API types; do not edit, run `{{pm_run}} generate:types`
 compose.yaml             every service; COMPOSE_PROFILES in .env picks dev or prod
 Caddyfile                the prod profile's reverse proxy and HTTPS
 .github/workflows/deploy.yml  optional deploy to a server over SSH
@@ -26,16 +26,16 @@ Caddyfile                the prod profile's reverse proxy and HTTPS
 
 ## Commands
 
-Run them at the project root. They need Docker; Node is only needed for the `npm run` shortcuts.
+Run them at the project root. They need Docker; Node is only needed for the `{{pm_run}}` shortcuts.
 
 | Task | Command |
 |------|---------|
-| Start everything | `docker compose up --build` (or `npm run dev`) |
-| Run a manage.py command | `docker compose exec backend python manage.py <command>` (or `npm run backend -- <command>`) |
+| Start everything | `docker compose up --build` (or `{{pm_run}} dev`) |
+| Run a manage.py command | `docker compose exec backend python manage.py <command>` (or `{{pm_backend}} <command>`) |
 | Make migrations after a model change | `docker compose exec backend python manage.py makemigrations` |
-| Regenerate the API types after a model change | `npm run generate:types` |
-| Run the tests | `npm test` |
-| Lint and type-check | `npm run lint` |
+| Regenerate the API types after a model change | `{{pm_run}} generate:types` |
+| Run the tests | `{{pm_run}} test` |
+| Lint and type-check | `{{pm_run}} lint` |
 | Logs | `docker compose logs --follow backend` |
 | Production settings for a server | `npx @django-stack/cli production --domain example.com` |
 
@@ -54,7 +54,7 @@ in a running container.
    `ModelStudio`.
 3. Run `makemigrations`; the backend migrates on its next start, or run
    `migrate`.
-4. Run `npm run generate:types`, then read it in the frontend as
+4. Run `{{pm_run}} generate:types`, then read it in the frontend as
    `frontend/AGENTS.md` shows.
 5. Add an API smoke test to `backend/content/tests/test_api.py`.