@django-stack/cli 0.6.0 → 0.8.0

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

@@ -1,9 +1,10 @@
 import { createRequire } from "node:module";
-import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { join, relative } from "node:path";
-import { execFileSync } from "node:child_process";
+import { chmodSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { execFileSync, spawnSync } from "node:child_process";
 import { randomBytes, randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
+import { createConnection, createServer } from "node:net";
 // src/env.ts
 /** Reads a .env file: KEY=value lines, comments and blank lines ignored. */
 function parseEnv(text) {
@@ -28,6 +29,18 @@ function setEnvValues(text, values) {
 	}
 	return result;
 }
+/**
+* A value as Docker Compose reads it literally: single-quoted when it has
+* characters Compose would interpolate or cut, such as `$`, `#` or a
+* space at either end.
+* Throws for a value it cannot quote.
+*/
+function quoteEnvValue(value) {
+	if (/[\r\n]/.test(value)) throw new Error("A value can't have a line break.");
+	if (!/[$#"`\\]|^\s|\s$|^'/.test(value)) return value;
+	if (value.includes("'")) throw new Error("A value with ' and other special characters can't be quoted.");
+	return `'${value}'`;
+}
 /** The oldest Python the backend runs on. */
 const MIN_PYTHON = "3.12";
 /** Runs a command and returns its trimmed output, or undefined when it fails. */
@@ -66,7 +79,7 @@ function dockerHelp(platform) {
 	if (platform === "win32") return ["Install Docker Desktop: winget install Docker.DockerDesktop", "or https://docs.docker.com/desktop/setup/install/windows-install/"];
 	return ["Install Docker Engine and the Compose plugin: https://docs.docker.com/engine/install/"];
 }
-function dockerStartHelp(platform) {
+function dockerStartHelp(platform = process.platform) {
 	if (platform === "linux") return ["Start it: sudo systemctl start docker"];
 	return ["Open Docker Desktop and wait until it says it is running."];
 }
@@ -88,6 +101,22 @@ function pythonVersion(runCommand) {
 		if (version) return version;
 	}
 }
+/** The one-line error when the Docker daemon is not reachable. */
+function dockerNotRunning(platform = process.platform) {
+	return `Docker not running. ${dockerStartHelp(platform)[0]}`;
+}
+/** Whether Docker's output says the daemon is not reachable, such as `failed to connect to the docker API`. */
+function isDockerDown(output) {
+	return /failed to connect to the docker API|Cannot connect to the Docker daemon|Is the docker daemon running|error during connect|docker_engine: The system cannot find the file specified/i.test(output);
+}
+/** Whether the Docker daemon answers. */
+function dockerRunning(runCommand = run) {
+	return Boolean(runCommand("docker", [
+		"version",
+		"--format",
+		"{{.Server.Version}}"
+	]));
+}
 /** Docker and Docker Compose, which run the project. */
 function checkDocker({ run: runCommand = run, platform = process.platform } = {}) {
 	const client = parseVersion(runCommand("docker", ["--version"]));
@@ -269,25 +298,144 @@ async function runDoctor(directory) {
 	});
 	return checks;
 }
-// src/secrets.ts
-/** A URL-safe random secret with `bytes` bytes of randomness. */
-function generateSecret(bytes = 32) {
-	return randomBytes(bytes).toString("base64url");
+// src/ports.ts
+const DEV_PORTS = [
+	{
+		name: "SITE_PORT",
+		port: 3e3,
+		label: "site"
+	},
+	{
+		name: "BACKEND_PORT",
+		port: 8e3,
+		label: "backend"
+	},
+	{
+		name: "MAIL_PORT",
+		port: 8025,
+		label: "Mailpit"
+	},
+	{
+		name: "S3_PORT",
+		port: 8333,
+		label: "local S3 service",
+		profile: "s3"
+	}
+];
+/** How many ports above the usual one to try. */
+const TRIES = 100;
+/** Whether something answers on 127.0.0.1:port. */
+function answers(port) {
+	return new Promise((resolve) => {
+		const socket = createConnection({
+			host: "127.0.0.1",
+			port
+		});
+		const done = (result) => {
+			socket.destroy();
+			resolve(result);
+		};
+		socket.setTimeout(500, () => done(false));
+		socket.once("connect", () => done(true));
+		socket.once("error", () => done(false));
+	});
 }
-/** The secrets a project's .env needs, by the name used in `{{secret:<name>}}`. */
-function generateProjectSecrets() {
+/** Whether this process can listen on 127.0.0.1:port. */
+function canListen(port) {
+	return new Promise((resolve) => {
+		const server = createServer();
+		server.once("error", () => resolve(false));
+		server.listen({
+			host: "127.0.0.1",
+			port,
+			exclusive: true
+		}, () => server.close(() => resolve(true)));
+	});
+}
+/**
+* Whether a port is free for Docker to publish on 127.0.0.1. Both checks,
+* because on macOS a server on all addresses does not stop a listen on
+* 127.0.0.1, but it does answer there.
+*/
+const isPortFree = async (port) => !await answers(port) && await canListen(port);
+/** The first free port from `preferred` up, leaving out `taken`. */
+async function freePort(preferred, taken = /* @__PURE__ */ new Set(), isFree = isPortFree) {
+	for (let port = preferred; port < preferred + TRIES && port <= 65535; port++) if (!taken.has(port) && await isFree(port)) return port;
+}
+/** The ports of a `.env`, by variable. */
+function envPorts(env) {
+	return Object.fromEntries(DEV_PORTS.map((item) => {
+		const value = Number(env[item.name]);
+		return [item.name, Number.isInteger(value) && value > 0 ? value : item.port];
+	}));
+}
+/**
+* The `.env` values for new ports: the ports, and the URLs on this machine
+* that contain them (SITE_URL and BACKEND_URL, and S3_PUBLIC_URL of the
+* local S3 service).
+*/
+function portValues(env, ports) {
+	const before = envPorts(env);
+	const values = {};
+	for (const item of DEV_PORTS) {
+		const port = ports[item.name];
+		if (port !== void 0 && port !== before[item.name]) values[item.name] = String(port);
+	}
+	const replacePort = (url, from, to) => {
+		if (!url || from === void 0 || to === void 0 || from === to) return void 0;
+		const local = new RegExp(`^(https?://(?:localhost|127\\.0\\.0\\.1)):${from}(?=/|$)`);
+		return local.test(url) ? url.replace(local, `$1:${to}`) : void 0;
+	};
+	for (const [name, port] of [
+		["SITE_URL", "SITE_PORT"],
+		["BACKEND_URL", "SITE_PORT"],
+		["S3_PUBLIC_URL", "S3_PORT"]
+	]) {
+		const url = replacePort(env[name], before[port], ports[port]);
+		if (url) values[name] = url;
+	}
+	return values;
+}
+/**
+* Free ports for the development services of a `.env`: the ones it has
+* when they are free, otherwise the next free ones up. Returns the moves,
+* or the ports that have no free one nearby.
+*/
+async function chooseFreePorts(env, profiles, isFree = isPortFree) {
+	const ports = envPorts(env);
+	const moves = [];
+	const stuck = [];
+	const taken = /* @__PURE__ */ new Set();
+	for (const item of DEV_PORTS) {
+		const current = ports[item.name];
+		if (item.profile && !profiles.includes(item.profile)) {
+			taken.add(current);
+			continue;
+		}
+		const port = !taken.has(current) && await isFree(current) ? current : await freePort(current + 1, taken, isFree);
+		if (port === void 0) {
+			stuck.push(item);
+			taken.add(current);
+			continue;
+		}
+		if (port !== current) moves.push({
+			label: item.label,
+			from: current,
+			to: port
+		});
+		ports[item.name] = port;
+		taken.add(port);
+	}
 	return {
-		django: generateSecret(48),
-		postgres: generateSecret(24),
-		api: generateSecret(32),
-		api_read: generateSecret(32),
-		preview: generateSecret(32),
-		revalidate: generateSecret(32),
-		admin: generateSecret(12),
-		umami_app: generateSecret(32),
-		umami_admin: generateSecret(24)
+		ports,
+		moves,
+		stuck
 	};
 }
+/** A line for a port that moved, such as `Port 3000 is in use, so the site uses 3001.` */
+function describeMove(move) {
+	return `Port ${move.from} is in use, so the ${move.label} uses ${move.to}.`;
+}
 // src/stack.ts
 const STACK_OPTIONS = [
 	{
@@ -295,6 +443,7 @@ const STACK_OPTIONS = [
 		flag: "--frontend",
 		message: "Frontend",
 		description: "The frontend framework",
+		bits: 4,
 		values: [
 			{
 				value: "astro",
@@ -339,6 +488,7 @@ const STACK_OPTIONS = [
 		flag: "--postgres",
 		message: "Postgres version",
 		description: "The bundled Postgres version",
+		bits: 2,
 		values: [{
 			value: "stable",
 			label: "Stable",
@@ -356,6 +506,7 @@ const STACK_OPTIONS = [
 		flag: "--analytics",
 		message: "Analytics",
 		description: "Page analytics",
+		bits: 2,
 		values: [{
 			value: "umami",
 			label: "Umami",
@@ -372,39 +523,52 @@ const STACK_OPTIONS = [
 		flag: "--tasks",
 		message: "Background tasks",
 		description: "The task queue",
-		values: [{
-			value: "huey",
-			label: "Huey",
-			hint: "a worker container with Valkey",
-			generated: true
-		}, {
-			value: "off",
-			label: "Off",
-			generated: false
-		}]
+		bits: 2,
+		values: [
+			{
+				value: "huey",
+				label: "Huey",
+				hint: "a worker container, the queue where the cache is",
+				generated: true
+			},
+			{
+				value: "off",
+				label: "Off",
+				hint: "tasks run in the request, no daily backups",
+				generated: true
+			},
+			{
+				value: "huey-valkey",
+				label: "Huey on Valkey",
+				hint: "the queue in Valkey",
+				generated: true
+			}
+		]
 	},
 	{
 		key: "cache",
 		flag: "--cache",
 		message: "Cache",
 		description: "The cache backend",
+		bits: 3,
 		values: [
 			{
 				value: "database",
 				label: "Database",
 				hint: "a Postgres table, nothing extra to run",
-				generated: false
+				generated: true
 			},
 			{
 				value: "valkey",
 				label: "Valkey",
 				hint: "in memory, Redis-compatible",
-				generated: false
+				generated: true
 			},
 			{
 				value: "off",
 				label: "Off",
-				generated: false
+				hint: "a cache per process",
+				generated: true
 			}
 		]
 	},
@@ -413,6 +577,7 @@ const STACK_OPTIONS = [
 		flag: "--notifications",
 		message: "Notifications",
 		description: "Notifications in the admin and by email",
+		bits: 2,
 		values: [{
 			value: "on",
 			label: "On",
@@ -429,6 +594,7 @@ const STACK_OPTIONS = [
 		flag: "--captcha",
 		message: "Captcha",
 		description: "The built-in captcha for forms",
+		bits: 2,
 		values: [{
 			value: "on",
 			label: "On",
@@ -445,6 +611,7 @@ const STACK_OPTIONS = [
 		flag: "--storage",
 		message: "Uploads in development",
 		description: "Where uploads go in development",
+		bits: 2,
 		values: [{
 			value: "local",
 			label: "Local files",
@@ -462,6 +629,7 @@ const STACK_OPTIONS = [
 		flag: "--package-manager",
 		message: "Package manager",
 		description: "The frontend's package manager",
+		bits: 3,
 		values: [
 			{
 				value: "pnpm",
@@ -479,14 +647,49 @@ const STACK_OPTIONS = [
 				generated: false
 			}
 		]
+	},
+	{
+		key: "media",
+		flag: "--media",
+		message: "Uploads in production",
+		description: "Where uploads go in production",
+		bits: 2,
+		values: [{
+			value: "server",
+			label: "On the server",
+			hint: "a Docker volume, backed up with the database",
+			generated: true
+		}, {
+			value: "s3",
+			label: "S3",
+			hint: "any S3-compatible service; credentials later",
+			generated: true
+		}]
 	}
 ];
+/**
+* The order of the prompts. It differs from STACK_OPTIONS (the preset order,
+* append-only): the cache comes before the tasks, whose queue follows it,
+* and uploads in production before uploads in development.
+*/
+const PROMPT_ORDER = (() => {
+	const keys = STACK_OPTIONS.map((option) => option.key).filter((key) => key !== "media" && key !== "cache");
+	keys.splice(keys.indexOf("storage"), 0, "media");
+	keys.splice(keys.indexOf("tasks"), 0, "cache");
+	return keys;
+})();
 function stackOption(key) {
 	const option = STACK_OPTIONS.find((candidate) => candidate.key === key);
 	if (!option) throw new Error(`Unknown stack option ${key}`);
 	return option;
 }
 const DEFAULT_STACK = Object.fromEntries(STACK_OPTIONS.map((option) => [option.key, option.values[0].value]));
+/** Where the task queue of a stack is: the database, Valkey, or none (tasks run in the request). */
+function taskQueue(stack) {
+	if (stack.tasks === "off") return "none";
+	if (stack.tasks === "huey-valkey" || stack.cache === "valkey") return "valkey";
+	return "database";
+}
 /** The frontends that run on Node, with a `frontend/` directory and a package manager. */
 const NODE_FRONTENDS = [
 	"astro",
@@ -499,26 +702,68 @@ function applies(key, stack) {
 	if (key === "packageManager") return stack.frontend === void 0 || NODE_FRONTENDS.includes(stack.frontend);
 	return true;
 }
-/** The preset format version, the first character of a code. */
-const VERSION = "a";
 const DIGITS = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
-/** A preset code for a stack: the version, then one character per option, trailing defaults left out. */
+/**
+* Preset codes are six characters: the format version, then the stack as
+* one number in five base62 digits. The options are bit fields of that
+* number, the first option in the lowest bits; the bits above the last
+* option are for options to come and must be 0.
+*
+* The number is multiplied by MULTIPLIER and offset by OFFSET (modulo
+* 62^5) before it is written, so codes look different from each other
+* rather than mostly zeros, and a mistyped code is usually refused instead
+* of meaning another stack. Both constants are part of the format: never
+* change them.
+*/
+const VERSION = "b";
+/** The first format: one character per option, trailing defaults left out. */
+const VERSION_A = "a";
+const LENGTH = 5;
+const MODULUS = 62n ** BigInt(LENGTH);
+/** The bits a code can hold: 2^29 is below 62^5. */
+const CAPACITY = 29;
+const MULTIPLIER = 387420489n;
+const OFFSET = 578291047n;
+/** The inverse of `value` modulo `modulus`. */
+function inverse(value, modulus) {
+	let [a, b, x, y] = [
+		value % modulus,
+		modulus,
+		1n,
+		0n
+	];
+	while (b) {
+		const q = a / b;
+		[a, b] = [b, a - q * b];
+		[x, y] = [y, x - q * y];
+	}
+	return (x % modulus + modulus) % modulus;
+}
+const MULTIPLIER_INVERSE = inverse(MULTIPLIER, MODULUS);
+/** A preset code for a stack: always six characters, such as `b8Kq2x`. */
 function encodePreset(stack) {
-	const digits = STACK_OPTIONS.map((option) => {
+	let number = 0n;
+	let shift = 0n;
+	for (const option of STACK_OPTIONS) {
 		const index = option.values.findIndex((value) => value.value === stack[option.key]);
 		if (index < 0) throw new Error(`${JSON.stringify(stack[option.key])} is not a ${option.key}.`);
-		return DIGITS[index];
-	}).join("").replace(/0+$/, "");
+		number |= BigInt(index) << shift;
+		shift += BigInt(option.bits);
+	}
+	let scrambled = (number * MULTIPLIER + OFFSET) % MODULUS;
+	let digits = "";
+	for (let position = 0; position < LENGTH; position++) {
+		digits = DIGITS[Number(scrambled % 62n)] + digits;
+		scrambled /= 62n;
+	}
 	return VERSION + digits;
 }
 const UPGRADE = "This preset needs a newer CLI. Run npx @django-stack/cli@latest init.";
-/** The stack of a preset code. Throws with a one-line reason for a bad code. */
-function decodePreset(code) {
-	if (!/^[0-9a-zA-Z]+$/.test(code)) throw new Error(`${JSON.stringify(code)} is not a preset.`);
-	if (code[0] !== VERSION) {
-		if (DIGITS.indexOf(code[0] ?? "") > DIGITS.indexOf(VERSION)) throw new Error(UPGRADE);
-		throw new Error(`${JSON.stringify(code)} is not a preset.`);
-	}
+function notAPreset(code) {
+	return /* @__PURE__ */ new Error(`${JSON.stringify(code)} is not a preset. Check the code, or run npx @django-stack/cli@latest init if it is from a newer CLI.`);
+}
+/** The stack of a code in the first format, which `init` wrote before 0.7. */
+function decodeVersionA(code) {
 	const digits = code.slice(1);
 	if (digits.length > STACK_OPTIONS.length) throw new Error(UPGRADE);
 	const stack = { ...DEFAULT_STACK };
@@ -530,6 +775,31 @@ function decodePreset(code) {
 	});
 	return stack;
 }
+/** The stack of a preset code. Throws with a one-line reason for a bad code. */
+function decodePreset(code) {
+	if (!/^[0-9a-zA-Z]+$/.test(code)) throw new Error(`${JSON.stringify(code)} is not a preset.`);
+	if (code[0] === VERSION_A) return decodeVersionA(code);
+	if (code[0] !== VERSION) {
+		if (DIGITS.indexOf(code[0] ?? "") > DIGITS.indexOf(VERSION)) throw new Error(UPGRADE);
+		throw new Error(`${JSON.stringify(code)} is not a preset.`);
+	}
+	if (code.length !== 6) throw notAPreset(code);
+	let scrambled = 0n;
+	for (const digit of code.slice(1)) scrambled = scrambled * 62n + BigInt(DIGITS.indexOf(digit));
+	let number = ((scrambled - OFFSET) % MODULUS + MODULUS) % MODULUS;
+	number = number * MULTIPLIER_INVERSE % MODULUS;
+	if (number >> BigInt(CAPACITY)) throw notAPreset(code);
+	const stack = {};
+	for (const option of STACK_OPTIONS) {
+		const index = Number(number & (1n << BigInt(option.bits)) - 1n);
+		number >>= BigInt(option.bits);
+		const value = option.values[index];
+		if (!value) throw notAPreset(code);
+		stack[option.key] = value.value;
+	}
+	if (number) throw notAPreset(code);
+	return stack;
+}
 const NAMED_PRESETS = {
 	blog: {
 		description: "Astro with everything on (the defaults)",
@@ -576,9 +846,270 @@ function pendingChoices(stack) {
 		}];
 	});
 }
+// src/project.ts
+/** The `.env` of `dstack run` on a development machine: the prod profile at https://site.localhost. */
+const RUN_ENV = ".env.run";
+const RUN_DOMAIN = "site.localhost";
+/**
+* The project's scripts that must be executable. npm and pnpm packages do
+* not keep the executable bit of non-bin files, so the templates arrive
+* without it.
+*/
+const EXECUTABLES = ["backend/entrypoint.sh", "backend/manage.py"];
+/** Makes the project's scripts executable for everyone who can read them. */
+function makeExecutable(directory) {
+	for (const file of EXECUTABLES) {
+		const path = join(directory, file);
+		try {
+			const { mode } = statSync(path);
+			const executable = mode | (mode & 292) >> 2;
+			if (executable !== mode) chmodSync(path, executable & 4095);
+		} catch {}
+	}
+}
+/** The project directory: `start` or the nearest parent with `compose.yaml` and `.env`. */
+function findProjectDirectory(start) {
+	let directory = resolve(start);
+	for (;;) {
+		if (existsSync(join(directory, "compose.yaml")) && existsSync(join(directory, ".env"))) return directory;
+		const parent = dirname(directory);
+		if (parent === directory) return void 0;
+		directory = parent;
+	}
+}
+function parseProfiles(value) {
+	return (value ?? "").split(",").map((profile) => profile.trim()).filter(Boolean);
+}
+function projectName(directory) {
+	try {
+		const match = readFileSync(join(directory, "compose.yaml"), "utf8").match(/^name:\s*["']?([\w.-]+)/m);
+		if (match?.[1]) return match[1];
+	} catch {}
+	return basename(directory).toLowerCase();
+}
+function fromEnv(directory, name, envFile, localRun) {
+	const env = parseEnv(readFileSync(join(directory, envFile), "utf8"));
+	const profiles = parseProfiles(env.COMPOSE_PROFILES);
+	const prod = profiles.includes("prod");
+	const suffix = prod ? "-prod" : "";
+	return {
+		directory,
+		name: localRun ? `${name}-run` : name,
+		env,
+		profiles,
+		prod,
+		localRun,
+		services: {
+			backend: `backend${suffix}`,
+			frontend: `frontend${suffix}`,
+			worker: `worker${suffix}`
+		},
+		composeArgs: localRun ? [
+			"--env-file",
+			envFile,
+			"--project-name",
+			`${name}-run`
+		] : [],
+		composeEnv: localRun ? {
+			ENV_FILE: envFile,
+			COMPOSE_PROFILES: env.COMPOSE_PROFILES ?? ""
+		} : {}
+	};
+}
+/** Reads the project in or above `start`. Throws with a one-line reason when there is none. */
+function readProject(start = ".") {
+	const directory = findProjectDirectory(start);
+	if (!directory) throw new Error(`No DjangoStack project in ${resolve(start)}: run this where compose.yaml and .env are.`);
+	makeExecutable(directory);
+	return fromEnv(directory, projectName(directory), ".env", false);
+}
+/** The local production run of a development project, when `.env.run` exists. */
+function readLocalRun(project) {
+	if (project.prod || project.localRun || !existsSync(join(project.directory, ".env.run"))) return void 0;
+	return fromEnv(project.directory, projectName(project.directory), RUN_ENV, true);
+}
+/** The `django-stack` section of the project's `package.json`. */
+function projectManifest(project) {
+	try {
+		return JSON.parse(readFileSync(join(project.directory, "package.json"), "utf8"))["django-stack"] ?? {};
+	} catch {
+		return {};
+	}
+}
+/**
+* The project's stack: from the preset `init` saved in `package.json`, or,
+* for projects from before that, the defaults with the storage from `.env`.
+* Analytics follow the `analytics` profile: projects from before Umami was
+* generated have the default in their preset without running it.
+*/
+function projectStack(project) {
+	const fromEnv = {
+		analytics: project.profiles.includes("analytics") ? "umami" : "off",
+		...project.env.CACHE_URL === void 0 ? {} : cacheStack(project.env)
+	};
+	const { preset } = projectManifest(project);
+	if (preset) try {
+		return {
+			...decodePreset(preset),
+			...fromEnv
+		};
+	} catch {}
+	return {
+		...DEFAULT_STACK,
+		...fromEnv,
+		storage: project.profiles.includes("s3") ? "s3" : "local"
+	};
+}
+const REDIS = /^(redis|rediss|valkey|valkeys):/;
+/**
+* The cache and the tasks a project's `.env` runs. Projects from before 0.7
+* have no TASKS_URL: their tasks follow a Redis cache, like the backend does.
+*/
+function cacheStack(env) {
+	const cacheUrl = env.CACHE_URL ?? "";
+	const cache = cacheUrl.startsWith("db:") ? "database" : REDIS.test(cacheUrl) ? "valkey" : "off";
+	const tasksUrl = env.TASKS_URL || (cache === "valkey" ? cacheUrl : "immediate://");
+	if (tasksUrl.startsWith("immediate:")) return {
+		cache,
+		tasks: "off"
+	};
+	return {
+		cache,
+		tasks: REDIS.test(tasksUrl) && cache !== "valkey" ? "huey-valkey" : "huey"
+	};
+}
+/** The URLs of a running project. */
+function projectUrls(project) {
+	if (project.prod) {
+		const site = (project.env.SITE_URL ?? "").replace(/\/$/, "");
+		return [{
+			label: "Site",
+			url: `${site}/`
+		}, {
+			label: "Admin",
+			url: `${site}/admin/`
+		}];
+	}
+	const ports = envPorts(project.env);
+	const site = (project.env.SITE_URL || `http://localhost:${ports.SITE_PORT}`).replace(/\/$/, "");
+	const urls = [
+		{
+			label: "Site",
+			url: site
+		},
+		{
+			label: "Admin",
+			url: `${site}/admin/`
+		},
+		{
+			label: "Mail",
+			url: `http://localhost:${ports.MAIL_PORT}`
+		}
+	];
+	if (project.profiles.includes("s3")) urls.push({
+		label: "S3",
+		url: `http://localhost:${ports.S3_PORT}`
+	});
+	return urls;
+}
+/** Runs a command with the terminal attached and returns its exit status. */
+const runInherit = (cmd, args, options) => {
+	const result = spawnSync(cmd, args, {
+		stdio: "inherit",
+		...options
+	});
+	if (result.error) return 127;
+	return result.status ?? 1;
+};
+/** The full `docker compose` argument list for a project. */
+function composeCommand(project, args) {
+	return [
+		"compose",
+		...project.composeArgs,
+		...args
+	];
+}
+function composeOptions(project) {
+	return {
+		cwd: project.directory,
+		env: {
+			...process.env,
+			...project.composeEnv
+		}
+	};
+}
+/** Runs `docker compose <args>` for the project with the terminal attached. */
+function compose(project, args, run = runInherit) {
+	return run("docker", composeCommand(project, args), composeOptions(project));
+}
+/** Runs `docker compose <args>` and captures the output. */
+function composeOutput(project, args) {
+	const result = spawnSync("docker", composeCommand(project, args), {
+		...composeOptions(project),
+		encoding: "utf8",
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		]
+	});
+	return {
+		status: result.status ?? 1,
+		output: `${result.stdout ?? ""}${result.stderr ?? ""}`.trim()
+	};
+}
+/** The running services of the project. */
+function runningServices(project) {
+	const result = spawnSync("docker", composeCommand(project, [
+		"ps",
+		"--services",
+		"--filter",
+		"status=running"
+	]), {
+		...composeOptions(project),
+		encoding: "utf8",
+		stdio: [
+			"ignore",
+			"pipe",
+			"ignore"
+		]
+	});
+	return result.status === 0 ? result.stdout.split("\n").filter(Boolean) : [];
+}
+/**
+* The project a command acts on: the local production run when it is the
+* one running, otherwise the project `.env` describes.
+*/
+function activeProject(project) {
+	const localRun = readLocalRun(project);
+	if (!localRun) return project;
+	if (runningServices(project).length) return project;
+	return runningServices(localRun).length ? localRun : project;
+}
+// src/secrets.ts
+/** A URL-safe random secret with `bytes` bytes of randomness. */
+function generateSecret(bytes = 32) {
+	return randomBytes(bytes).toString("base64url");
+}
+/** The secrets a project's .env needs, by the name used in `{{secret:<name>}}`. */
+function generateProjectSecrets() {
+	return {
+		django: generateSecret(48),
+		postgres: generateSecret(24),
+		api: generateSecret(32),
+		api_read: generateSecret(32),
+		preview: generateSecret(32),
+		revalidate: generateSecret(32),
+		admin: generateSecret(12),
+		umami_app: generateSecret(32),
+		umami_admin: generateSecret(24)
+	};
+}
 // src/version.ts
 /** The version of this package, the same for every @django-stack package. */
 const CLI_VERSION = createRequire(import.meta.url)("../package.json").version;
+/** The npm package of the CLI. */
+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);
@@ -598,16 +1129,49 @@ function umamiEnv(databaseUrl, secrets) {
 		UMAMI_DATABASE_URL: umamiDatabaseUrl(databaseUrl)
 	};
 }
-/** The local S3 service of the `s3` profile. It accepts any credentials. */
-const LOCAL_S3 = {
-	S3_BUCKET: "media",
-	S3_ENDPOINT_URL: "http://s3:8333",
-	S3_REGION: "us-east-1",
-	S3_ACCESS_KEY_ID: "local",
-	S3_SECRET_ACCESS_KEY: "local",
-	S3_PUBLIC_URL: "http://localhost:8333/media",
-	S3_CREATE_BUCKET: "1"
+const CACHE_URLS = {
+	database: "db://",
+	valkey: "redis://cache:6379/0",
+	off: "locmem://"
 };
+const TASK_ENV = {
+	database: {
+		TASKS_URL: "db://",
+		TASK_WORKERS: "1"
+	},
+	valkey: {
+		TASKS_URL: "redis://cache:6379/1",
+		TASK_WORKERS: "1"
+	},
+	none: {
+		TASKS_URL: "immediate://",
+		TASK_WORKERS: "0"
+	}
+};
+/** The `.env` values of a cache and a task queue: CACHE_URL, TASKS_URL and TASK_WORKERS. */
+function cacheEnv(stack) {
+	return {
+		CACHE_URL: CACHE_URLS[stack.cache],
+		...TASK_ENV[taskQueue(stack)]
+	};
+}
+/** 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 ?? ""));
+}
+/** The local S3 service of the `s3` profile, published on `port`. It accepts any credentials. */
+function localS3(port = 8333) {
+	return {
+		S3_BUCKET: "media",
+		S3_ENDPOINT_URL: "http://s3:8333",
+		S3_REGION: "us-east-1",
+		S3_ACCESS_KEY_ID: "local",
+		S3_SECRET_ACCESS_KEY: "local",
+		S3_PUBLIC_URL: `http://localhost:${port}/media`,
+		S3_CREATE_BUCKET: "1"
+	};
+}
+const LOCAL_S3 = localS3();
 const TEXT_EXTENSIONS = /\.(py|ts|tsx|mjs|js|jsx|json|astro|vue|svelte|css|md|yaml|yml|toml|txt|html|sh|svg)$|Dockerfile$|gitignore$|\.dockerignore$|env\.example$/;
 function defaultTemplatesDir() {
 	return fileURLToPath(new URL("../templates", import.meta.url));
@@ -670,6 +1234,7 @@ function scaffold(options) {
 	cpSync(join(templates, "backend"), join(target, "backend"), { recursive: true });
 	cpSync(frontendTemplate, join(target, "frontend"), { recursive: true });
 	renameSync(join(target, "gitignore"), join(target, ".gitignore"));
+	makeExecutable(target);
 	const about = join(target, "frontend", "template.json");
 	const frontend = JSON.parse(readFileSync(about, "utf8"));
 	rmSync(about);
@@ -680,7 +1245,9 @@ function scaffold(options) {
 		frontend_url: frontend.url,
 		frontend_security: frontend.security,
 		cli_version: CLI_VERSION,
-		preset: options.preset ?? "a"
+		preset: options.preset ?? encodePreset(DEFAULT_STACK),
+		site_port: String(options.ports?.SITE_PORT ?? 3e3),
+		mail_port: String(options.ports?.MAIL_PORT ?? 8025)
 	};
 	const files = walk(target);
 	for (const file of files) {
@@ -709,7 +1276,14 @@ function scaffold(options) {
 		profiles.push("analytics");
 		env = setEnvValues(env, umamiEnv(parseEnv(env).DATABASE_URL ?? "", secrets));
 	}
+	const cache = cacheEnv({
+		cache: options.cache ?? "database",
+		tasks: options.tasks ?? "huey"
+	});
+	env = setEnvValues(env, cache);
+	if (usesValkey(cache)) profiles.push("valkey");
 	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" });
 	writeFileSync(join(target, ".env"), env, { mode: 384 });
 	writeFileSync(join(target, ".env.example"), envExample);
@@ -791,6 +1365,15 @@ function relativeDirectory(directory) {
 	return path.startsWith("..") ? directory : path;
 }
 // src/production.ts
+/** The S3 settings that uploads to S3 need and that are empty. */
+function missingS3(env) {
+	return [
+		"S3_BUCKET",
+		"S3_REGION",
+		"S3_ACCESS_KEY_ID",
+		"S3_SECRET_ACCESS_KEY"
+	].filter((name) => !env[name]);
+}
 function validateDomain(domain) {
 	if (!/^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/i.test(domain)) return "Enter a domain name such as example.com, without https://.";
 }
@@ -847,8 +1430,9 @@ function productionEnv(devEnv, options) {
 			S3_PUBLIC_URL: "",
 			S3_CREATE_BUCKET: "0"
 		});
-		todo.push("Set the S3_* variables to your S3 service, or leave them empty to keep uploads on the server.");
+		if (options.media !== "s3") todo.push("Set the S3_* variables to your S3 service, or leave them empty to keep uploads on the server.");
 	}
+	if (options.media === "s3" && missingS3(parseEnv(setEnvValues(devEnv, values))).length) todo.push("Set the S3_* variables to your S3 service: uploads go to S3 in production.");
 	if (!current.ADMIN_EMAIL || current.ADMIN_EMAIL.endsWith("@example.com")) todo.push("Set ADMIN_EMAIL to your address.");
 	if (current.SEED_DEMO_CONTENT === "1") todo.push("Set SEED_DEMO_CONTENT=0 unless the site should start with the demo pages and posts.");
 	return {
@@ -857,4 +1441,4 @@ function productionEnv(devEnv, options) {
 		todo
 	};
 }
-export { stackOption as C, checkTools as D, runDoctor as E, parseEnv as O, resolvePreset as S, generateSecret as T, STACK_OPTIONS as _, lockBackend as a, encodePreset as b, scaffold as c, umamiEnv as d, validateProjectName as f, NAMED_PRESETS as g, DEFAULT_STACK as h, LOCAL_S3 as i, setEnvValues as k, timeZones as l, CLI_VERSION as m, validateDomain as n, normalizeDatabaseUrl as o, validateTimeZone as p, FRONTENDS as r, relativeDirectory as s, productionEnv as t, toProjectName as u, applies as v, generateProjectSecrets as w, pendingChoices as x, decodePreset as y };
+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 };