kizlo 0.9.0 → 0.10.0

package/dist/cli/commands/init.js

@@ -1,9 +1,8 @@
-import { dockerAvailable } from "../wp/docker.js";
 import { addDependencyArgs, detectImportAlias, detectPackageManager, ensureGitignored, getVersion, loadEnvFiles, runCommandAsync } from "../utils.js";
 import { PRESETS, detectPreset, getPreset } from "../presets/index.js";
 import { fetchTemplate } from "../presets/source.js";
-import { adaptFile, changesFor, fileEntries, patchEntries, readManifest } from "../presets/template.js";
-import { collectConnectionFromEnv, collectConnectionInteractively, dirPath, nextStepsNote, orCancel, setupLocalWordPress, syncRemote, validate, withApiPath, writeEnv } from "./_setup.js";
+import { adaptFile, changesFor, fileEntries, isOlderVersion, minCliError, patchEntries, readManifest, resolveDependencies } from "../presets/template.js";
+import { collectConnectionFromEnv, collectConnectionInteractively, dirPath, nextStepsNote, orCancel, readEnvExample, resolveEnvKeys, setupLocalWordPress, syncRemote, validate, withApiPath, writeEnv } from "./_setup.js";
 import { applyLayoutPatches, buildScaffoldContext, kizloConfigTemplate, reportScaffold, scaffoldFile, writeGeneratedContract } from "./_wiring.js";
 import path from "node:path";
 import fs from "node:fs";
@@ -32,7 +31,6 @@ function detectAppDir(cwd, hasSrcDir) {
 	return hasSrcDir ? "src/app" : "app";
 }
 async function collectInteractively(ctx) {
-	const conn = await collectConnectionInteractively(ctx.preset);
 	const dir = orCancel(await p.text({
 		message: "Kizlo directory",
 		initialValue: defaultDir(ctx.hasSrcDir),
@@ -49,7 +47,7 @@ async function collectInteractively(ctx) {
 		})).trim();
 	}
 	return {
-		...conn,
+		...await collectConnectionInteractively(ctx.preset),
 		dir,
 		alias
 	};
@@ -60,7 +58,7 @@ async function collectInteractively(ctx) {
 * later. Never fails — `--yes` always scaffolds a fillable project.
 */
 function collectFromEnv(ctx) {
-	const conn = collectConnectionFromEnv(ctx.preset);
+	const conn = collectConnectionFromEnv(ctx.envKeys);
 	const dir = defaultDir(ctx.hasSrcDir);
 	return {
 		...conn,
@@ -71,40 +69,23 @@ function collectFromEnv(ctx) {
 function readPkg(pkgPath) {
 	return JSON.parse(fs.readFileSync(pkgPath, "utf8"));
 }
-function kizloDep(pkg) {
-	return pkg.dependencies?.kizlo ?? pkg.devDependencies?.kizlo;
-}
-/** A bare `x.y.z` from a version spec (range prefix and pre-release/build metadata dropped); undefined if none. */
-function coerceVersion(spec) {
-	const match = /(\d+)\.(\d+)\.(\d+)/.exec(spec);
-	return match ? [
-		Number(match[1]),
-		Number(match[2]),
-		Number(match[3])
-	] : void 0;
-}
-/** Whether `have` is a strictly older release than `want`; false when either can't be compared. */
-function isOlder(have, want) {
-	const a = coerceVersion(have);
-	const b = coerceVersion(want);
-	if (!a || !b) return false;
-	for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i] < b[i];
-	return false;
-}
 /**
-* The template is authoritative for the kizlo version: it declares `kizloVersion` in its manifest
-* (stamped at release), falling back to the running CLI's version in-repo before the first stamp.
-* When the project's kizlo is older, upgrade the project up to it and say so — a deliberate pin is
-* never changed silently. Never downgrades.
+* The template is authoritative for the pinned versions: it declares `dependencies`/`devDependencies`
+* in its manifest (stamped at release), falling back to the running CLI's version for `kizlo` in-repo
+* before the first stamp. For each declared package the project already has at an older release, upgrade
+* it up to the template's pin and say so — a deliberate pin is never changed silently. Never downgrades,
+* and never adds a package the project doesn't already have (a missing `kizlo` is installed separately).
 */
-async function alignKizloVersion(cwd, pm, pkg, manifest) {
-	const want = manifest.kizloVersion ?? `^${getVersion()}`;
-	const have = kizloDep(pkg);
-	if (!have || !isOlder(have, want)) return;
-	const s = p.spinner();
-	s.start(`Upgrading kizlo from ${have} to ${want}`);
-	const ok = await runCommandAsync(addDependencyArgs(pm, `kizlo@${want}`), cwd, "ignore");
-	s.stop(ok ? `Upgraded kizlo to ${want}` : `Could not upgrade kizlo automatically — install kizlo@${want} yourself`);
+async function alignDependencies(cwd, pm, pkg, manifest) {
+	const { dependencies, devDependencies } = resolveDependencies(manifest);
+	for (const [name, want] of [...Object.entries(dependencies), ...Object.entries(devDependencies)]) {
+		const have = pkg.dependencies?.[name] ?? pkg.devDependencies?.[name];
+		if (!have || !isOlderVersion(have, want)) continue;
+		const s = p.spinner();
+		s.start(`Upgrading ${name} from ${have} to ${want}`);
+		const ok = await runCommandAsync(addDependencyArgs(pm, `${name}@${want}`), cwd, "ignore");
+		s.stop(ok ? `Upgraded ${name} to ${want}` : `Could not upgrade ${name} automatically — install ${name}@${want} yourself`);
+	}
 }
 const init = defineCommand({
 	meta: {
@@ -178,76 +159,85 @@ const init = defineCommand({
 			process.exit(1);
 		}
 		if (yes) loadEnvFiles(cwd);
-		const setup = yes ? collectFromEnv({
-			cwd,
-			hasSrcDir,
-			preset
-		}) : await collectInteractively({
-			cwd,
-			hasSrcDir,
-			preset
-		});
-		if (args.alias !== void 0) setup.alias = String(args.alias).trim();
-		setup.alias = aliasWithSlash(setup.alias);
-		if (setup.mode === "local" && !await dockerAvailable()) {
-			p.cancel("Docker isn't available — start Docker (or install it) and re-run, or choose “Use my own WordPress”.");
-			process.exit(1);
-		}
-		if (!hasKizlo) {
-			const spec = `kizlo@^${getVersion()}`;
-			const s = p.spinner();
-			s.start(`Installing kizlo with ${pm}`);
-			const ok = await runCommandAsync(addDependencyArgs(pm, spec), cwd, "ignore");
-			s.stop(ok ? "Installed kizlo" : "Could not install kizlo automatically");
-			if (!ok) p.log.warn(`Install it yourself: ${addDependencyArgs(pm, spec).join(" ")}`);
-		}
-		if (preset.apiPath && setup.baseUrl) setup.baseUrl = withApiPath(setup.baseUrl, preset.apiPath);
-		await setupLocalWordPress(cwd, setup);
-		await writeEnv(cwd, preset, setup, {
-			force,
-			yes
-		});
-		await syncRemote(setup);
-		const dirRel = setup.dir.replace(/^\.\//, "").replace(/\/+$/, "");
-		const serverDirRel = path.join(dirRel, "server");
-		const clientUrl = setup.siteUrl && !sameOrigin(setup.siteUrl, setup.baseUrl) ? setup.baseUrl : void 0;
-		const scaffold = buildScaffoldContext(cwd, {
-			dirRel,
-			appDir: detectAppDir(cwd, hasSrcDir),
-			alias: setup.alias,
-			clientUrl
-		});
-		const files = [{
-			label: "Kizlo config",
-			relPath: "kizlo.config.ts",
-			contents: kizloConfigTemplate(dirRel, setup.alias, setup.devPath)
-		}];
 		let manifest;
+		let fetched;
 		if (preset.template) {
-			const fetched = await fetchTemplate(preset.template);
-			try {
-				manifest = readManifest(fetched.dir);
-				await alignKizloVersion(cwd, pm, pkg, manifest);
-				for (const entry of fileEntries(changesFor(manifest, "init"))) files.push(adaptFile(fetched.dir, entry, manifest.conventions, scaffold));
-			} finally {
+			fetched = await fetchTemplate(preset.template);
+			manifest = readManifest(fetched.dir);
+			const minErr = minCliError(manifest);
+			if (minErr) {
 				fetched.cleanup();
+				p.cancel(minErr);
+				process.exit(1);
 			}
-		} else if (preset.scaffolds) files.push(...preset.scaffolds(scaffold));
-		const scaffolded = [];
-		for (const file of files) scaffolded.push({
-			file,
-			result: await scaffoldFile(cwd, file, {
+		}
+		const envKeys = resolveEnvKeys(preset, manifest);
+		try {
+			const setup = yes ? collectFromEnv({
+				cwd,
+				hasSrcDir,
+				preset,
+				envKeys
+			}) : await collectInteractively({
+				cwd,
+				hasSrcDir,
+				preset
+			});
+			if (args.alias !== void 0) setup.alias = String(args.alias).trim();
+			setup.alias = aliasWithSlash(setup.alias);
+			if (!hasKizlo) {
+				const spec = `kizlo@${manifest?.dependencies?.kizlo ?? `^${getVersion()}`}`;
+				const s = p.spinner();
+				s.start(`Installing kizlo with ${pm}`);
+				const ok = await runCommandAsync(addDependencyArgs(pm, spec), cwd, "ignore");
+				s.stop(ok ? "Installed kizlo" : "Could not install kizlo automatically");
+				if (!ok) p.log.warn(`Install it yourself: ${addDependencyArgs(pm, spec).join(" ")}`);
+			}
+			if (preset.apiPath && setup.baseUrl) setup.baseUrl = withApiPath(setup.baseUrl, preset.apiPath);
+			await setupLocalWordPress(cwd, setup);
+			await writeEnv(cwd, envKeys, setup, {
 				force,
-				yes
-			})
-		});
-		writeGeneratedContract(cwd, serverDirRel);
-		const gitignore = ensureGitignored(cwd, ".env");
-		for (const { file, result } of scaffolded) reportScaffold(file, result, yes);
-		if (manifest) applyLayoutPatches(cwd, patchEntries(changesFor(manifest, "init")), manifest.conventions, scaffold);
-		if (gitignore !== "present") p.log.success(`${gitignore === "created" ? "Created" : "Updated"} .gitignore (ignoring .env)`);
-		nextStepsNote(setup);
-		p.outro("Kizlo is ready 🎉");
+				yes,
+				exampleTemplate: fetched ? readEnvExample(fetched.dir) : void 0
+			});
+			await syncRemote(setup);
+			const dirRel = setup.dir.replace(/^\.\//, "").replace(/\/+$/, "");
+			const serverDirRel = path.join(dirRel, "server");
+			const clientUrl = setup.siteUrl && !sameOrigin(setup.siteUrl, setup.baseUrl) ? setup.baseUrl : void 0;
+			const scaffold = buildScaffoldContext(cwd, {
+				dirRel,
+				appDir: detectAppDir(cwd, hasSrcDir),
+				alias: setup.alias,
+				clientUrl
+			});
+			const files = [{
+				label: "Kizlo config",
+				relPath: "kizlo.config.ts",
+				contents: kizloConfigTemplate(dirRel, setup.alias, setup.mode === "local")
+			}];
+			if (manifest && fetched) {
+				await alignDependencies(cwd, pm, pkg, manifest);
+				for (const entry of fileEntries(changesFor(manifest, "init"))) files.push(adaptFile(fetched.dir, entry, manifest.conventions, scaffold));
+			} else if (preset.scaffolds) files.push(...preset.scaffolds(scaffold));
+			const scaffolded = [];
+			for (const file of files) scaffolded.push({
+				file,
+				result: await scaffoldFile(cwd, file, {
+					force,
+					yes
+				})
+			});
+			writeGeneratedContract(cwd, serverDirRel);
+			const gitignore = ensureGitignored(cwd, ".env");
+			ensureGitignored(cwd, ".kizlo/");
+			for (const { file, result } of scaffolded) reportScaffold(file, result, yes);
+			if (manifest) applyLayoutPatches(cwd, patchEntries(changesFor(manifest, "init")), manifest.conventions, scaffold);
+			if (gitignore !== "present") p.log.success(`${gitignore === "created" ? "Created" : "Updated"} .gitignore (ignoring .env)`);
+			nextStepsNote(setup);
+			p.outro("Kizlo is ready 🎉");
+		} finally {
+			fetched?.cleanup();
+		}
 	}
 });
 

package/dist/cli/commands/test.js

@@ -1,4 +1,4 @@
-import { createStack } from "../wp/docker.js";
+import { createStack, dockerHint, dockerStatus } from "../wp/docker.js";
 import { isSeeded, recordedPort } from "../wp/utils.js";
 import { log } from "../daemon/logger.js";
 import { isFree } from "../wp/ports.js";
@@ -19,8 +19,8 @@ async function resolve(cwd) {
 	};
 }
 /**
-* The host port to bring the test stack up on. Unlike the dev stack (rebuilt every run), the
-* test stack is reused and its tests connect via the URL recorded in the credentials artifact —
+* The host port to bring the test WordPress up on. Unlike local dev WordPress (rebuilt every run), the
+* test WordPress is reused and its tests connect via the URL recorded in the credentials artifact —
 * so the port can't just be re-chosen each time:
 *
 * - A **running** stack keeps its live published port (fast reruns stay on the same URL).
@@ -40,7 +40,7 @@ async function resolveTestPort(cfg, stack, fresh) {
 		const recorded = recordedPort();
 		if (recorded !== void 0) {
 			if (await isFree(recorded)) return recorded;
-			log.error(`The test stack's port ${recorded} (from a previous run) is now held by something else.\nFree that port, or run \`kizlo test reset\` to rebuild on a fresh one.`);
+			log.error(`The test WordPress port ${recorded} (from a previous run) is now held by something else.\nFree that port, or run \`kizlo test reset\` to rebuild on a fresh one.`);
 			process.exit(1);
 		}
 	}
@@ -50,7 +50,7 @@ async function resolveTestPort(cfg, stack, fresh) {
 	});
 }
 /**
-* Boot the test stack on a resolved host port and seed it once (idempotent — skips seeding when
+* Boot the test WordPress on a resolved host port and seed it once (idempotent — skips seeding when
 * already seeded). Returns the port-bound stack and the port, so callers report the real URL.
 */
 async function bringUp(cfg, stack, fresh = false) {
@@ -59,8 +59,8 @@ async function bringUp(cfg, stack, fresh = false) {
 		...cfg,
 		port
 	}));
-	await withSpinner("Starting WordPress test stack", () => bound.composeUp(), "WordPress test stack ready");
-	if (await isSeeded()) log.info("Stack already seeded — skipping seed.");
+	await withSpinner("Starting test WordPress", () => bound.composeUp(), "Test WordPress ready");
+	if (await isSeeded()) log.info("Test WordPress already seeded — skipping seed.");
 	else await withSpinner("Seeding WordPress", () => runSeeds({
 		port,
 		fixtures: cfg.fixtures
@@ -90,30 +90,45 @@ function spawnTest(command, pm) {
 		child.on("close", (code) => resolvePromise(code ?? 0));
 	});
 }
+/** Log which test command is about to run, then spawn it and resolve with its exit code. */
+function runProjectTests(cfg) {
+	log.info(cfg.command ? `Running: ${cfg.command}` : `Running: ${testCommand(cfg.packageManager).join(" ")}`);
+	return spawnTest(cfg.command, cfg.packageManager);
+}
 const runArgs = {
 	teardown: {
 		type: "boolean",
-		description: "Tear down the test stack after tests finish (default: leave it running for fast reruns)"
+		description: "Tear down the test WordPress after tests finish (default: leave it running for fast reruns)"
 	},
 	reset: {
 		type: "boolean",
 		description: "Wipe the database and reseed before running"
 	}
 };
-/** Boot (+ seed) the stack, run the project's test script, then leave it up (or tear down). */
+/**
+* Run the project's tests. When `test.local` is set, boot (+ seed) local WordPress first, run the
+* suite (JS then the plugin's PHPUnit) against it, then leave it up (or tear down). Without
+* `test.local`, there's no Docker WordPress to manage — just run the project's own test script.
+*/
 async function runSuite({ args }) {
-	const { cfg, stack: probe } = await resolve(process.cwd());
+	const cfg = await resolveTestConfig(process.cwd());
+	if (!cfg.local) process.exit(await runProjectTests(cfg));
+	const status = await dockerStatus();
+	if (status !== "running") {
+		log.error(dockerHint(status));
+		process.exit(1);
+	}
+	const probe = createStack(testStack(cfg));
 	if (args.reset) await withSpinner("Wiping WordPress database", () => probe.composeDown({ volumes: true }), "Database wiped");
 	const { stack } = await bringUp(cfg, probe, Boolean(args.reset));
-	log.info(cfg.command ? `Running: ${cfg.command}` : `Running: ${testCommand(cfg.packageManager).join(" ")}`);
 	let code = 1;
 	try {
-		const jsCode = await spawnTest(cfg.command, cfg.packageManager);
+		const jsCode = await runProjectTests(cfg);
 		const phpCode = await runPluginPhpunit(cfg);
 		code = jsCode !== 0 ? jsCode : phpCode;
 	} finally {
-		if (args.teardown) await withSpinner("Tearing down WordPress test stack", () => stack.composeDown(), "WordPress test stack stopped");
-		else log.info("Stack left running for fast reruns — `kizlo test stop` to stop it, or rerun with --teardown.");
+		if (args.teardown) await withSpinner("Tearing down test WordPress", () => stack.composeDown(), "Test WordPress stopped");
+		else log.info("Test WordPress left running for fast reruns — `kizlo test stop` to stop it, or rerun with --teardown.");
 	}
 	process.exit(code);
 }
@@ -121,45 +136,30 @@ const subCommands = {
 	stop: defineCommand({
 		meta: {
 			name: "stop",
-			description: "Stop the WordPress test stack, keeping the database volume"
+			description: "Stop the test WordPress, keeping the database volume"
 		},
 		async run() {
 			const { stack } = await resolve(process.cwd());
-			await withSpinner("Stopping WordPress test stack", () => stack.composeStop(), "Stack stopped (volumes kept)");
-		}
-	}),
-	down: defineCommand({
-		meta: {
-			name: "down",
-			description: "Stop and remove the test stack containers"
-		},
-		args: { volumes: {
-			type: "boolean",
-			alias: "v",
-			description: "Also drop the database volume"
-		} },
-		async run({ args }) {
-			const { stack } = await resolve(process.cwd());
-			await withSpinner("Removing WordPress test stack", () => stack.composeDown({ volumes: args.volumes }), args.volumes ? "Stack removed (volumes dropped)" : "Stack removed (volumes kept)");
+			await withSpinner("Stopping test WordPress", () => stack.composeStop(), "Test WordPress stopped (volumes kept)");
 		}
 	}),
 	reset: defineCommand({
 		meta: {
 			name: "reset",
-			description: "Wipe the database and reseed a fresh WordPress test stack"
+			description: "Wipe the database and reseed fresh test WordPress"
 		},
 		async run() {
 			const { cfg, stack } = await resolve(process.cwd());
 			await withSpinner("Wiping WordPress database", () => stack.composeDown({ volumes: true }), "Database wiped");
 			const { port } = await bringUp(cfg, stack, true);
-			log.success(`Stack ready on http://localhost:${port} — credentials at ${cfg.credentialsPath}`);
+			log.success(`Test WordPress ready on http://localhost:${port} — credentials at ${cfg.credentialsPath}`);
 		}
 	})
 };
 const test = defineCommand({
 	meta: {
 		name: "test",
-		description: "Manage the WordPress test stack and run tests (stop | down | reset)"
+		description: "Run tests against local WordPress (stop | reset)"
 	},
 	args: runArgs,
 	subCommands,

package/dist/cli/daemon/config.js

@@ -1,3 +1,4 @@
+import { LOCAL_DIR_REL } from "../wp/constants.js";
 import { credentialsPath, findConfigDir } from "../wp/utils.js";
 import { log } from "./logger.js";
 import { detectPackageManager } from "../utils.js";
@@ -14,13 +15,13 @@ const configSchema = z.object({
 	alias: z.string().optional(),
 	name: z.string().optional(),
 	dev: z.object({
-		path: z.string().optional(),
+		local: z.boolean().optional(),
 		port: z.number().int().positive().optional(),
 		dbPort: z.number().int().positive().optional(),
-		byo: z.string().optional(),
 		fixtures: z.array(fixtureSchema).optional()
 	}).optional(),
 	test: z.object({
+		local: z.boolean().optional(),
 		port: z.number().int().positive().optional(),
 		fixtures: z.array(fixtureSchema).optional(),
 		packageManager: z.enum([
@@ -108,6 +109,7 @@ async function resolveTestConfig(cwd) {
 	const test = fileConfig?.test ?? {};
 	return {
 		configDir,
+		local: Boolean(test.local),
 		project: `${resolveStackName(configDir, fileConfig?.name)}-test`,
 		command: test.command,
 		port: test.port ?? DEFAULT_TEST_PORT,
@@ -118,33 +120,26 @@ async function resolveTestConfig(cwd) {
 	};
 }
 /**
-* Whether a local WordPress dev stack is configured (`dev.path` is set). When false, `kizlo dev`
-* has no stack to boot and runs the contract watcher alone — the path a bring-your-own-WordPress
-* project takes. Loads `kizlo.config.*` from the config dir; a missing config counts as no stack.
+* Whether this project runs local WordPress under `kizlo dev` — `dev.local` is `true` in
+* `kizlo.config.*`. When false, `kizlo dev` has nothing to boot and runs the contract watcher alone,
+* the path a project pointing at its own WordPress takes. The flag is written by `create`/`init` when
+* local WordPress is chosen, and lives next to the rest of the `dev` config, so it's committed and
+* survives `kizlo dev reset`.
 */
-async function hasDevStack(cwd) {
+async function usesLocalWordPress(cwd) {
 	const fileConfig = await loadConfigFile(findConfigDir(cwd));
-	return Boolean(fileConfig?.dev?.path);
+	return Boolean(fileConfig?.dev?.local);
 }
 /**
-* Resolve the `dev` block from `kizlo.config.*` into concrete values for the `dev`
-* command, applying defaults (port 8080). `dev.path` is required — the whole
-* WordPress install lives there, so we make the user choose a real folder rather
-* than hide it under a default. Callers gate on {@link hasDevStack} first, since a
-* project without a local stack runs the watcher alone rather than reaching here.
+* Resolve the `dev` block from `kizlo.config.*` into concrete values for the `dev` command, applying
+* defaults (port 8080). The install folder is fixed at `.kizlo/local` — no longer a config choice — so
+* there's nothing required here. Callers gate on {@link usesLocalWordPress} first, since a project
+* without local WordPress runs the watcher alone rather than reaching here.
 */
 async function resolveDevConfig(cwd) {
 	const configDir = findConfigDir(cwd);
 	const fileConfig = await loadConfigFile(configDir);
 	const dev = fileConfig?.dev ?? {};
-	if (!dev.path) {
-		log.error("`dev.path` is required in kizlo.config — it's the folder your local WordPress lives in.\nPick a real, visible folder (it persists your site between runs), e.g. dev: { path: \"wordpress\" }.");
-		process.exit(1);
-	}
-	if (dev.byo && dev.fixtures?.length) {
-		log.error("`dev.byo` and `dev.fixtures` are mutually exclusive — byo imports an existing site, so it brings its own data.");
-		process.exit(1);
-	}
 	return {
 		configDir,
 		project: `${resolveStackName(configDir, fileConfig?.name)}-dev`,
@@ -152,12 +147,11 @@ async function resolveDevConfig(cwd) {
 		portExplicit: dev.port !== void 0,
 		dbPort: dev.dbPort ?? DEFAULT_DEV_DB_PORT,
 		dbPortExplicit: dev.dbPort !== void 0,
-		byo: dev.byo ? path.resolve(configDir, dev.byo) : void 0,
 		fixtures: dev.fixtures ?? [],
-		wordpressPath: dev.path,
-		wordpressDir: path.resolve(configDir, dev.path)
+		wordpressPath: LOCAL_DIR_REL,
+		wordpressDir: path.resolve(configDir, LOCAL_DIR_REL)
 	};
 }
 
 //#endregion
-export { DEFAULT_DEV_DB_PORT, DEFAULT_DEV_PORT, hasDevStack, resolveConfig, resolveDevConfig, resolveStackName, resolveTestConfig };
+export { DEFAULT_DEV_DB_PORT, DEFAULT_DEV_PORT, resolveConfig, resolveDevConfig, resolveStackName, resolveTestConfig, usesLocalWordPress };

package/dist/cli/presets/base.js

@@ -1,9 +1,11 @@
+import { DEFAULT_ENV_KEYS } from "../utils.js";
+
 //#region src/cli/presets/base.ts
 const base = {
 	id: "base",
 	label: "Generic (no framework detected)",
 	detect: () => 1,
-	baseUrlEnvKey: "KIZLO_BACKEND_URL",
+	envKeys: DEFAULT_ENV_KEYS,
 	scaffolds(ctx) {
 		return [{
 			label: "Kizlo server instance",
@@ -24,7 +26,7 @@ function clientEntry(ctx) {
 import { contract } from "./${ctx.serverDirName}/generated"
 
 // Your Kizlo backend runs on a different origin than this app. Swap in your bundler's
-// public env var (e.g. import.meta.env.VITE_KIZLO_BACKEND_URL) to set it per environment.
+// public env var (e.g. import.meta.env.VITE_KIZLO_API_URL) to set it per environment.
 export const client = createKizloClient(contract, { url: "${ctx.clientUrl}" })
 `;
 	return `import { createKizloClient } from "kizlo"

package/dist/cli/presets/nextjs.js

@@ -8,7 +8,6 @@ const nextjs = {
 			...ctx.pkg.devDependencies
 		}.next ? 100 : 0;
 	},
-	baseUrlEnvKey: "NEXT_PUBLIC_KIZLO_BACKEND_URL",
 	apiPath: "/api/kizlo",
 	template: "nextjs"
 };

package/dist/cli/presets/template.js

@@ -1,3 +1,4 @@
+import { getVersion } from "../utils.js";
 import { resolvePatchTargetPath } from "./patch.js";
 import z from "zod/v4";
 import path from "node:path";
@@ -58,9 +59,36 @@ const bootstrapSchema = z.object({
 	flags: z.array(z.string()).default([])
 });
 const changeSchema = z.discriminatedUnion("kind", [fileSchema, patchSchema]);
+/**
+* The `.env` key names the scaffold writes and the pinned runtime later reads — the one part of the
+* wiring contract that can drift when the scaffold-time CLI and the pinned runtime disagree. Declared
+* here as data so the scaffold writes whatever names the pinned runtime expects. Semantic slots only;
+* the CLI still fills each value (generate a secret, provision Docker, prompt for a remote URL).
+*/
+const envSchema = z.object({
+	baseUrl: z.string(),
+	remote: z.object({
+		siteSecret: z.string(),
+		wpUrl: z.string(),
+		wpUsername: z.string(),
+		wpPassword: z.string()
+	}),
+	local: z.object({
+		connect: z.string(),
+		siteSecret: z.string(),
+		wpUrl: z.string(),
+		wpUsername: z.string(),
+		wpPassword: z.string()
+	})
+});
+/** A package name → version-range map, package.json's own vocabulary. */
+const depsSchema = z.record(z.string(), z.string());
 const manifestSchema = z.object({
 	framework: z.string(),
-	kizloVersion: z.string().optional(),
+	env: envSchema.optional(),
+	dependencies: depsSchema.optional(),
+	devDependencies: depsSchema.optional(),
+	minCli: z.string().optional(),
 	bootstrap: bootstrapSchema.optional(),
 	conventions: conventionsSchema,
 	base: z.array(changeSchema).default([]),
@@ -88,6 +116,52 @@ function readManifest(templateDir) {
 	return manifestSchema.parse(JSON.parse(fs.readFileSync(manifestPath, "utf8")));
 }
 /**
+* The dependencies a scaffolded project should pin, from the manifest. `kizlo` is always present —
+* every project needs it — so it falls back to the running CLI's version in-repo before the first
+* stamped release; any other declared package is taken verbatim (a template only lists packages it has
+* a version for). Framework packages release in lockstep with `kizlo`, so a stamped manifest carries
+* them all at the same released version.
+*/
+function resolveDependencies(manifest) {
+	return {
+		dependencies: {
+			kizlo: `^${getVersion()}`,
+			...manifest.dependencies
+		},
+		devDependencies: { ...manifest.devDependencies }
+	};
+}
+/** A bare `x.y.z` from a version spec (range prefix and pre-release/build metadata dropped); undefined if none. */
+function coerceVersion(spec) {
+	const match = /(\d+)\.(\d+)\.(\d+)/.exec(spec);
+	return match ? [
+		Number(match[1]),
+		Number(match[2]),
+		Number(match[3])
+	] : void 0;
+}
+/** Whether `have` is a strictly older release than `want`; false when either can't be compared. */
+function isOlderVersion(have, want) {
+	const a = coerceVersion(have);
+	const b = coerceVersion(want);
+	if (!a || !b) return false;
+	for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i] < b[i];
+	return false;
+}
+/**
+* The loud-failure backstop: an error message when the running CLI is too old to apply this manifest,
+* or `undefined` when it's fine. Dormant by design — a manifest with no `minCli` never fails, so the
+* check is inert until a structural change bumps the floor. The first CLI-incompatible manifest change
+* sets `minCli`; from then on older CLIs (that already ship this check) stop with a clear message
+* instead of silently under-wiring the project.
+*/
+function minCliError(manifest) {
+	if (!manifest.minCli) return void 0;
+	const running = getVersion();
+	if (!isOlderVersion(running, manifest.minCli)) return void 0;
+	return `This template needs the kizlo CLI >= ${manifest.minCli} (you have ${running}). Run \`npx kizlo@latest\` and try again.`;
+}
+/**
 * The changes a command applies: the shared `base` set plus the command's own section. `create` gets
 * `base + create` (plumbing plus the demo pages); `init` gets `base + init` (plumbing plus any
 * init-only surgical patches). `base` is applied first so a later section can override it.
@@ -193,4 +267,4 @@ function rendersHtml(file) {
 }
 
 //#endregion
-export { adaptFile, changesFor, fileEntries, findRootLayout, isExample, patchEntries, readManifest, resolvePatch };
+export { adaptFile, changesFor, fileEntries, findRootLayout, isExample, isOlderVersion, minCliError, patchEntries, readManifest, resolveDependencies, resolvePatch };