kizlo 0.8.1 → 0.8.3

package/dist/cli/commands/_setup.js

@@ -321,11 +321,11 @@ async function syncRemote(conn) {
 	});
 	if (!sync.ok) p.log.warn(`Could not sync the site settings to WordPress (${sync.error}) — make sure the kizlo plugin is active, then set them from the Kizlo settings.`);
 }
-/** The shared "Next steps" note, branched on whether a local dev stack was set up. */
-function nextStepsNote(mode, prefix = "") {
-	p.note([
+/** The "Next steps" lines, branched on whether a local dev stack was set up. */
+function nextStepsLines(mode, prefix = "") {
+	return [
 		...mode === "local" ? [
-			`Start your local WordPress dev stack (also watches your extensions):`,
+			`Start your local WordPress dev stack:`,
 			`  ${prefix}npx kizlo dev`,
 			``
 		] : [
@@ -335,8 +335,12 @@ function nextStepsNote(mode, prefix = "") {
 		],
 		`Generate the contract once for production builds:`,
 		`  ${prefix}npx kizlo generate`
-	].join("\n"), "Next steps");
+	];
+}
+/** The shared "Next steps" note, branched on whether a local dev stack was set up. */
+function nextStepsNote(mode, prefix = "") {
+	p.note(nextStepsLines(mode, prefix).join("\n"), "Next steps");
 }
 
 //#endregion
-export { collectConnectionFromEnv, collectConnectionInteractively, dirPath, nextStepsNote, orCancel, setupLocalWordPress, syncRemote, validate, withApiPath, writeEnv };
+export { collectConnectionFromEnv, collectConnectionInteractively, dirPath, nextStepsLines, nextStepsNote, orCancel, setupLocalWordPress, syncRemote, validate, withApiPath, writeEnv };

package/dist/cli/commands/_wiring.js

@@ -0,0 +1,116 @@
+import { resolveModuleImport, writeFileIfAbsent } from "../utils.js";
+import { applyPatchToSource, patchChanged, renderPatchCode } from "../presets/patch.js";
+import { findRootLayout, patchEntries, resolvePatch } from "../presets/template.js";
+import { orCancel } from "./_setup.js";
+import { CONTRACT_BARREL } from "../daemon/generate.js";
+import path from "node:path";
+import fs from "node:fs";
+import * as p from "@clack/prompts";
+
+//#region src/cli/commands/_wiring.ts
+/** The kizlo.config.ts a scaffolded project gets: the Kizlo directory, optional import alias, and —
+*  for a local dev setup — the WordPress install folder so `kizlo dev` knows where it lives. */
+function kizloConfigTemplate(dir, alias, devPath) {
+	return `import { defineConfig } from "kizlo/config"
+
+export default defineConfig({
+	dir: "${dir}",${alias ? `\n\talias: "${alias}",` : ""}${devPath ? `\n\tdev: { path: "${devPath}" },` : ""}
+})
+`;
+}
+/**
+* Build the {@link ScaffoldContext} that adapts a template's tokenized paths and imports to a real
+* project. `dirRel` is the Kizlo home directory, `appDir` the App Router directory, and `alias` the
+* import-alias prefix (empty for relative imports). The server-entry import is resolved per calling
+* file so each scaffolded file references the server through the right specifier.
+*/
+function buildScaffoldContext(cwd, { dirRel, appDir, alias, clientUrl }) {
+	const serverDirRel = path.join(dirRel, "server");
+	return {
+		kizloDir: dirRel,
+		serverDirName: path.basename(serverDirRel),
+		serverEntryPath: path.join(serverDirRel, "index.ts"),
+		clientPath: path.join(dirRel, "client.ts"),
+		appDir,
+		serverImport: (fromDir) => resolveModuleImport(cwd, serverDirRel, fromDir, alias),
+		clientUrl
+	};
+}
+/**
+* The single overwrite policy for every scaffolded file: create it when absent, overwrite on
+* `--force`, and otherwise ask before clobbering an existing file (keeping it when the user
+* declines or when running non-interactively with `--yes`). Every scaffolded file routes through
+* here rather than deciding for itself, so new files inherit the same behavior for free.
+*/
+async function scaffoldFile(cwd, file, opts) {
+	const absPath = path.join(cwd, file.relPath);
+	const existed = fs.existsSync(absPath);
+	if (existed) {
+		let overwrite = opts.force;
+		if (!opts.force && !opts.yes) {
+			p.log.warn(`${file.label} already exists at ${file.relPath}`);
+			overwrite = orCancel(await p.confirm({
+				message: "Overwrite it?",
+				initialValue: true
+			}));
+		}
+		if (!overwrite) return "kept";
+	}
+	fs.mkdirSync(path.dirname(absPath), { recursive: true });
+	fs.writeFileSync(absPath, file.contents);
+	return existed ? "overwritten" : "created";
+}
+/** Report a {@link scaffoldFile} outcome in the setup commands' usual voice. */
+function reportScaffold(file, result, yes) {
+	if (result === "kept") p.log.info(`Kept existing ${file.label} (${file.relPath})${yes ? " — pass --force to overwrite" : ""}`);
+	else p.log.success(`${result === "overwritten" ? "Overwrote" : "Created"} ${file.label} (${file.relPath})`);
+}
+/** Seed the generated-contract directory so imports resolve before the first `kizlo watch`/`generate`. */
+function writeGeneratedContract(cwd, serverDirRel) {
+	const generatedDirRel = path.join(serverDirRel, "generated");
+	writeFileIfAbsent(path.join(cwd, generatedDirRel, "contract.json"), "{}\n");
+	writeFileIfAbsent(path.join(cwd, generatedDirRel, "index.ts"), CONTRACT_BARREL);
+}
+/**
+* Merge Kizlo wiring into files the project already owns (the root layout's SEO exports). Never
+* aborts: the target is resolved by identity (the layout that renders `<html>`), and on any doubt —
+* not found, not parseable — the resolved payload is printed at the end with placement instructions
+* rather than written to a guessed-at file. A confident apply is an idempotent upsert: it replaces
+* our exports if present, adds them if not.
+*/
+function applyLayoutPatches(cwd, manifest, scaffold) {
+	const manualSteps = [];
+	for (const entry of patchEntries(manifest)) {
+		const resolved = resolvePatch(entry, manifest.tokens, scaffold);
+		const target = findRootLayout(cwd, scaffold.appDir, resolved.relPath);
+		if (!target) {
+			manualSteps.push(resolved);
+			p.log.info(`Couldn't find your ${resolved.label} to wire Kizlo into — see the code to add below`);
+			continue;
+		}
+		const relTarget = path.relative(cwd, target);
+		const src = fs.readFileSync(target, "utf8");
+		let applied;
+		try {
+			applied = applyPatchToSource(src, resolved);
+		} catch {
+			manualSteps.push(resolved);
+			p.log.warn(`Couldn't parse your ${resolved.label} (${relTarget}) — see the code to add below`);
+			continue;
+		}
+		const { text, changes } = applied;
+		if (patchChanged(changes)) {
+			fs.writeFileSync(target, text);
+			const parts = [
+				...changes.replacedExports.length ? [`replaced ${changes.replacedExports.join(", ")}`] : [],
+				...changes.addedExports.length ? [`added ${changes.addedExports.join(", ")}`] : [],
+				...changes.addedImports.length ? ["imports"] : []
+			];
+			p.log.success(`Wired Kizlo into your ${resolved.label} (${relTarget}) — ${parts.join(", ")}`);
+		} else p.log.info(`Your ${resolved.label} is already wired (${relTarget})`);
+	}
+	for (const resolved of manualSteps) p.note(renderPatchCode(resolved), `Add these to your ${resolved.label} (the layout that renders <html>)`);
+}
+
+//#endregion
+export { applyLayoutPatches, buildScaffoldContext, kizloConfigTemplate, reportScaffold, scaffoldFile, writeGeneratedContract };

package/dist/cli/commands/create.js

@@ -1,65 +1,90 @@
 import { dockerAvailable } from "../wp/docker.js";
-import { detectPackageManager, getVersion } from "../utils.js";
+import { availablePackageManagers, detectInvokingPackageManager, ensureGitignored, frameworkCreateArgs, getVersion, installArgs, runCommandAsync, runCommandCaptured } from "../utils.js";
 import { printBanner } from "../banner.js";
 import { getPreset } from "../presets/index.js";
-import { collectConnectionInteractively, nextStepsNote, orCancel, setupLocalWordPress, syncRemote, validate, withApiPath, writeEnv } from "./_setup.js";
+import { fetchTemplate } from "../presets/source.js";
+import { adaptOwnFile, ownEntries, readManifest } from "../presets/template.js";
+import { collectConnectionInteractively, nextStepsLines, orCancel, setupLocalWordPress, syncRemote, validate, withApiPath, writeEnv } from "./_setup.js";
+import { applyLayoutPatches, buildScaffoldContext, kizloConfigTemplate, reportScaffold, scaffoldFile, writeGeneratedContract } from "./_wiring.js";
 import z from "zod/v4";
 import path from "node:path";
 import fs from "node:fs";
 import { defineCommand } from "citty";
 import * as p from "@clack/prompts";
-import { downloadTemplate } from "giget";
 
 //#region src/cli/commands/create.ts
-/** GitHub repo the full templates are fetched from, matching the release-tag scheme. */
-const TEMPLATE_REPO = "github:kizlo-io/kizlo";
 /**
 * The templates `create` can scaffold from. Each id is both the `templates/<id>` folder and the
-* preset that drives its WordPress setup.
+* preset that drives its WordPress setup and framework bootstrap.
 */
 const TEMPLATES = ["nextjs"];
 function isTemplate(value) {
 	return TEMPLATES.includes(value);
 }
 const projectName = validate(z.string().trim().min(1, "Required").refine((value) => !value.startsWith(".") && !value.includes("/") && !value.includes("\\"), "Enter a folder name (letters, numbers, dashes)"));
+/** Package managers `create` can wire the getting-started steps for, in display order. */
+const PACKAGE_MANAGERS = [
+	"pnpm",
+	"npm",
+	"yarn",
+	"bun"
+];
 /**
-* Resolve where the template is fetched from. Defaults to the GitHub repo pinned to the release
-* tag matching this CLI version (`kizlo-v<version>`), so the template and the `kizlo` dependency it
-* pulls come from the same release. `KIZLO_TEMPLATE_REF` overrides the ref (e.g. `main`) and
-* `KIZLO_TEMPLATE_LOCAL_DIR` points at a local `templates/` directory for pre-release development.
+* Pin the `kizlo` dependency in the freshly bootstrapped `package.json`. The template is
+* authoritative for the version (`kizloVersion` in its manifest, stamped at release), falling back to
+* the running CLI's version in-repo before the first stamp. The dependency is only recorded, not
+* installed — the getting-started note tells the user to run install.
 */
-function templateSource(template) {
-	const localDir = process.env.KIZLO_TEMPLATE_LOCAL_DIR;
-	if (localDir) return { local: path.resolve(localDir, template) };
-	return { remote: `${TEMPLATE_REPO}/templates/${template}#${process.env.KIZLO_TEMPLATE_REF ?? `kizlo-v${getVersion()}`}` };
+function recordKizloDependency(dir, manifest) {
+	const pkgPath = path.join(dir, "package.json");
+	const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+	pkg.dependencies ??= {};
+	pkg.dependencies.kizlo = manifest.kizloVersion ?? `^${getVersion()}`;
+	fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, "	")}\n`);
+}
+/**
+* The argv `create` runs to bootstrap a fresh base app with the framework's own official CLI, built
+* from the template manifest's `bootstrap` (initializer + flags) — the template is the single source
+* of truth for the framework. The CLI owns only the package-manager mechanics: {@link frameworkCreateArgs}
+* assembles the `<pm> create …` invocation, and the `{{pm}}` token in the flags is substituted with the
+* chosen manager (e.g. `--use-{{pm}}` → `--use-pnpm`).
+*/
+function bootstrapArgs(manifest, pm, name) {
+	if (!manifest.bootstrap) return void 0;
+	const flags = manifest.bootstrap.flags.map((flag) => flag.replaceAll("{{pm}}", pm));
+	return frameworkCreateArgs(pm, manifest.bootstrap.initializer, name, flags);
 }
 /**
-* Copy the template into `dir`, then make it a standalone project: rewrite the `workspace:*` Kizlo
-* dependency to this CLI's version and name the package after the project folder. The template's
-* `kizlo.template.json` is an internal build input, so it's removed once the copy lands.
+* Layer Kizlo's wiring onto a freshly bootstrapped app in `dir`, from an already-fetched template
+* directory + manifest. The framework CLI has produced the base project (package.json, config,
+* tsconfig, the root layout); this drives the manifest — the same engine `init` uses — to record the
+* `kizlo` dependency, write `kizlo.config.ts`, scaffold the manifest's own files (wiring plus the demo
+* starter pages), seed the generated contract, ignore `.env`, and patch the root layout's SEO exports.
+* The target directory layout comes straight from the manifest tokens, which the bootstrap flags are
+* chosen to match, so files land where the manifest expects. Fresh files are written with `force`,
+* silently replacing the framework defaults.
 */
-async function scaffoldTemplate(template, dir, name) {
-	const source = templateSource(template);
-	if (source.local) {
-		if (!fs.existsSync(source.local)) throw new Error(`Local template not found: ${source.local}`);
-		fs.cpSync(source.local, dir, { recursive: true });
-	} else await downloadTemplate(source.remote, {
-		dir,
-		forceClean: true
+async function applyManifestWiring(dir, templateDir, manifest, opts) {
+	const { kizloDir, appDir, alias } = manifest.tokens;
+	const scaffold = buildScaffoldContext(dir, {
+		dirRel: kizloDir,
+		appDir,
+		alias,
+		clientUrl: void 0
 	});
-	fs.rmSync(path.join(dir, "kizlo.template.json"), { force: true });
-	const pkgPath = path.join(dir, "package.json");
-	if (!fs.existsSync(pkgPath)) {
-		fs.rmSync(dir, {
-			recursive: true,
-			force: true
-		});
-		throw new Error(`Template "${template}" wasn't found at ${source.remote ?? source.local}. This ref may predate the templates — retry with KIZLO_TEMPLATE_REF=main.`);
-	}
-	const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
-	pkg.name = name;
-	if (pkg.dependencies?.kizlo === "workspace:*") pkg.dependencies.kizlo = `^${getVersion()}`;
-	fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, "	")}\n`);
+	recordKizloDependency(dir, manifest);
+	const files = [{
+		label: "Kizlo config",
+		relPath: "kizlo.config.ts",
+		contents: kizloConfigTemplate(kizloDir, alias, opts.devPath)
+	}, ...ownEntries(manifest, { includeStarter: true }).map((entry) => adaptOwnFile(templateDir, entry, manifest.tokens, scaffold))];
+	for (const file of files) reportScaffold(file, await scaffoldFile(dir, file, {
+		force: true,
+		yes: false
+	}), false);
+	writeGeneratedContract(dir, path.join(kizloDir, "server"));
+	ensureGitignored(dir, ".env");
+	applyLayoutPatches(dir, manifest, scaffold);
 }
 const create = defineCommand({
 	meta: {
@@ -119,21 +144,60 @@ const create = defineCommand({
 			p.cancel(`No preset for template "${template}".`);
 			process.exit(1);
 		}
+		const installed = availablePackageManagers(PACKAGE_MANAGERS);
+		const invokingPm = detectInvokingPackageManager();
+		const defaultPm = invokingPm && installed.includes(invokingPm) ? invokingPm : installed[0];
+		const pm = orCancel(await p.select({
+			message: "Package manager",
+			options: installed.map((id) => ({
+				value: id,
+				label: id
+			})),
+			initialValue: defaultPm
+		}));
 		const conn = await collectConnectionInteractively(preset);
 		if (preset.apiPath && conn.baseUrl) conn.baseUrl = withApiPath(conn.baseUrl, preset.apiPath);
 		if (conn.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);
 		}
+		const fetched = await fetchTemplate(template);
+		const fail = (message) => {
+			fetched.cleanup();
+			p.cancel(message);
+			process.exit(1);
+		};
+		const manifest = readManifest(fetched.dir);
+		const bootstrap = bootstrapArgs(manifest, pm, name);
+		if (!bootstrap) {
+			fetched.cleanup();
+			p.cancel(`Template "${template}" can't be scaffolded — its manifest declares no framework bootstrap.`);
+			process.exit(1);
+		}
 		const s = p.spinner();
-		s.start(`Creating ${name} from the ${template} template`);
+		s.start(`Creating ${name} with the ${preset.label} CLI`);
+		const scaffold = runCommandCaptured(bootstrap, cwd);
+		s.stop(scaffold.ok ? `Created ${name} with the ${preset.label} CLI` : `${preset.label} setup failed`);
+		if (!scaffold.ok) {
+			if (scaffold.output) p.log.error(scaffold.output);
+			fail(`${preset.label} setup failed — see the output above and try again.`);
+		}
 		try {
-			await scaffoldTemplate(template, dir, name);
-			s.stop(`Created ${name}`);
+			await applyManifestWiring(dir, fetched.dir, manifest, { devPath: conn.devPath });
 		} catch (error) {
-			s.stop("Could not create the project");
-			p.cancel(error instanceof Error ? error.message : String(error));
-			process.exit(1);
+			fail(error instanceof Error ? error.message : String(error));
+		}
+		fetched.cleanup();
+		let depsInstalled = false;
+		if (orCancel(await p.confirm({
+			message: "Install dependencies now?",
+			initialValue: true
+		}))) {
+			const is = p.spinner();
+			is.start(`Installing dependencies with ${pm}`);
+			depsInstalled = await runCommandAsync(installArgs(pm), dir, "ignore");
+			is.stop(depsInstalled ? "Installed dependencies" : "Could not install dependencies");
+			if (!depsInstalled) p.log.warn(`Install them yourself: cd ${name} && ${installArgs(pm).join(" ")}`);
 		}
 		await setupLocalWordPress(dir, conn);
 		await writeEnv(dir, preset, conn, {
@@ -141,9 +205,12 @@ const create = defineCommand({
 			yes: false
 		});
 		await syncRemote(conn);
-		const pm = detectPackageManager(dir);
-		p.note([`cd ${name}`, `${pm} install`].join("\n"), "Get started");
-		nextStepsNote(conn.mode);
+		p.note([
+			`cd ${name}`,
+			...depsInstalled ? [] : [`${pm} install`],
+			``,
+			...nextStepsLines(conn.mode)
+		].join("\n"), "Next steps");
 		p.outro("Kizlo is ready 🎉");
 	}
 });

package/dist/cli/commands/init.js

@@ -1,10 +1,11 @@
 import { dockerAvailable } from "../wp/docker.js";
-import { addDependencyArgs, detectImportAlias, detectPackageManager, ensureGitignored, getVersion, loadEnvFiles, resolveModuleImport, runCommand, writeFileIfAbsent } from "../utils.js";
+import { addDependencyArgs, detectImportAlias, detectPackageManager, ensureGitignored, getVersion, loadEnvFiles, runCommand } from "../utils.js";
 import { printBanner } from "../banner.js";
 import { PRESETS, detectPreset, getPreset } from "../presets/index.js";
+import { fetchTemplate } from "../presets/source.js";
+import { adaptOwnFile, ownEntries, readManifest } from "../presets/template.js";
 import { collectConnectionFromEnv, collectConnectionInteractively, dirPath, nextStepsNote, orCancel, setupLocalWordPress, syncRemote, validate, withApiPath, writeEnv } from "./_setup.js";
-import { CONTRACT_BARREL } from "../daemon/generate.js";
-import { applyPatchToSource, patchChanged, resolvePatch, resolvePatchTargetPath, templatePatches } from "../presets/patch.js";
+import { applyLayoutPatches, buildScaffoldContext, kizloConfigTemplate, reportScaffold, scaffoldFile, writeGeneratedContract } from "./_wiring.js";
 import path from "node:path";
 import fs from "node:fs";
 import { defineCommand } from "citty";
@@ -18,14 +19,6 @@ function defaultDir(hasSrcDir) {
 function aliasWithSlash(alias) {
 	return alias ? `${alias.replace(/\/+$/, "")}/` : "";
 }
-function kizloConfigTemplate(dir, alias, devPath) {
-	return `import { defineConfig } from "kizlo/config"
-
-export default defineConfig({
-	dir: "${dir}",${alias ? `\n\talias: "${alias}",` : ""}${devPath ? `\n\tdev: { path: "${devPath}" },` : ""}
-})
-`;
-}
 /** Whether two URLs share an origin (scheme + host + port); false when either can't be parsed. */
 function sameOrigin(a, b) {
 	try {
@@ -39,35 +32,6 @@ function detectAppDir(cwd, hasSrcDir) {
 	if (fs.existsSync(path.join(cwd, "app"))) return "app";
 	return hasSrcDir ? "src/app" : "app";
 }
-/**
-* The single overwrite policy for every scaffolded file: create it when absent, overwrite on
-* `--force`, and otherwise ask before clobbering an existing file (keeping it when the user
-* declines or when running non-interactively with `--yes`). Every scaffolded file routes through
-* here rather than deciding for itself, so new files inherit the same behavior for free.
-*/
-async function scaffoldFile(cwd, file, opts) {
-	const absPath = path.join(cwd, file.relPath);
-	const existed = fs.existsSync(absPath);
-	if (existed) {
-		let overwrite = opts.force;
-		if (!opts.force && !opts.yes) {
-			p.log.warn(`${file.label} already exists at ${file.relPath}`);
-			overwrite = orCancel(await p.confirm({
-				message: "Overwrite it?",
-				initialValue: true
-			}));
-		}
-		if (!overwrite) return "kept";
-	}
-	fs.mkdirSync(path.dirname(absPath), { recursive: true });
-	fs.writeFileSync(absPath, file.contents);
-	return existed ? "overwritten" : "created";
-}
-/** Report a {@link scaffoldFile} outcome in init's usual voice. */
-function reportScaffold(file, result, yes) {
-	if (result === "kept") p.log.info(`Kept existing ${file.label} (${file.relPath})${yes ? " — pass --force to overwrite" : ""}`);
-	else p.log.success(`${result === "overwritten" ? "Overwrote" : "Created"} ${file.label} (${file.relPath})`);
-}
 async function collectInteractively(ctx) {
 	const conn = await collectConnectionInteractively(ctx.preset);
 	const dir = orCancel(await p.text({
@@ -108,6 +72,41 @@ 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.
+*/
+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 = runCommand(addDependencyArgs(pm, `kizlo@${want}`), cwd, "ignore");
+	s.stop(ok ? `Upgraded kizlo to ${want}` : `Could not upgrade kizlo automatically — install kizlo@${want} yourself`);
+}
 const init = defineCommand({
 	meta: {
 		name: "init",
@@ -168,6 +167,10 @@ const init = defineCommand({
 			preset = detectPreset(initCtx);
 			if (preset.id !== "base") p.log.success(`${preset.label} detected`);
 		}
+		if (preset.template === "nextjs" && !fs.existsSync(path.join(cwd, "app")) && !fs.existsSync(path.join(cwd, "src/app"))) {
+			p.cancel("Kizlo needs the Next.js App Router — no `app` or `src/app` directory found. The Pages Router isn't supported.");
+			process.exit(1);
+		}
 		if (yes) loadEnvFiles(cwd);
 		const setup = yes ? collectFromEnv({
 			cwd,
@@ -185,11 +188,12 @@ const init = defineCommand({
 			process.exit(1);
 		}
 		if (!hasKizlo) {
+			const spec = `kizlo@^${getVersion()}`;
 			const s = p.spinner();
 			s.start(`Installing kizlo with ${pm}`);
-			const ok = runCommand(addDependencyArgs(pm, "kizlo@latest"), cwd, "ignore");
+			const ok = runCommand(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, "kizlo@latest").join(" ")}`);
+			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);
@@ -201,20 +205,28 @@ const init = defineCommand({
 		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 = {
-			kizloDir: dirRel,
-			serverDirName: path.basename(serverDirRel),
-			serverEntryPath: path.join(serverDirRel, "index.ts"),
-			clientPath: path.join(dirRel, "client.ts"),
+		const scaffold = buildScaffoldContext(cwd, {
+			dirRel,
 			appDir: detectAppDir(cwd, hasSrcDir),
-			serverImport: (fromDir) => resolveModuleImport(cwd, serverDirRel, fromDir, setup.alias),
+			alias: setup.alias,
 			clientUrl
-		};
+		});
 		const files = [{
 			label: "Kizlo config",
 			relPath: "kizlo.config.ts",
 			contents: kizloConfigTemplate(dirRel, setup.alias, setup.devPath)
-		}, ...preset.scaffolds(scaffold)];
+		}];
+		let manifest;
+		if (preset.template) {
+			const fetched = await fetchTemplate(preset.template);
+			try {
+				manifest = readManifest(fetched.dir);
+				alignKizloVersion(cwd, pm, pkg, manifest);
+				for (const entry of ownEntries(manifest)) files.push(adaptOwnFile(fetched.dir, entry, manifest.tokens, scaffold));
+			} finally {
+				fetched.cleanup();
+			}
+		} else if (preset.scaffolds) files.push(...preset.scaffolds(scaffold));
 		const scaffolded = [];
 		for (const file of files) scaffolded.push({
 			file,
@@ -223,47 +235,10 @@ const init = defineCommand({
 				yes
 			})
 		});
-		const generatedDirRel = path.join(serverDirRel, "generated");
-		writeFileIfAbsent(path.join(cwd, generatedDirRel, "contract.json"), "{}\n");
-		writeFileIfAbsent(path.join(cwd, generatedDirRel, "index.ts"), CONTRACT_BARREL);
+		writeGeneratedContract(cwd, serverDirRel);
 		const gitignore = ensureGitignored(cwd, ".env");
 		for (const { file, result } of scaffolded) reportScaffold(file, result, yes);
-		for (const patch of templatePatches(preset.id)) {
-			const resolved = resolvePatch(patch, scaffold);
-			const abs = resolvePatchTargetPath(cwd, resolved.relPath);
-			if (!abs) {
-				p.log.info(`Skipped ${resolved.label} wiring — ${resolved.relPath} not found (add it yourself)`);
-				continue;
-			}
-			const relTarget = path.relative(cwd, abs);
-			const src = fs.readFileSync(abs, "utf8");
-			let text;
-			let changes;
-			try {
-				({text, changes} = applyPatchToSource(src, resolved, { replaceConflicts: force }));
-			} catch (err) {
-				p.log.error(`Could not parse ${resolved.label} (${relTarget}) to wire Kizlo into it: ${err instanceof Error ? err.message : String(err)}`);
-				throw err;
-			}
-			if (!force && !yes && changes.keptExports.length) {
-				p.log.warn(`${resolved.label} (${relTarget}) already defines ${changes.keptExports.join(", ")}`);
-				if (orCancel(await p.confirm({
-					message: "Replace with Kizlo's version?",
-					initialValue: true
-				}))) ({text, changes} = applyPatchToSource(src, resolved, { replaceConflicts: true }));
-			}
-			if (patchChanged(changes)) {
-				fs.writeFileSync(abs, text);
-				const parts = [
-					...changes.replacedExports.length ? [`replaced ${changes.replacedExports.join(", ")}`] : [],
-					...changes.addedExports.length ? [`added ${changes.addedExports.join(", ")}`] : [],
-					...changes.addedImports.length ? ["imports"] : []
-				];
-				p.log.success(`Wired Kizlo into your ${resolved.label} (${relTarget}) — ${parts.join(", ")}`);
-			}
-			if (changes.keptExports.length) p.log.info(`Kept your existing ${changes.keptExports.join(", ")} in ${resolved.label} — pass --force to replace`);
-			else if (!patchChanged(changes)) p.log.info(`Your ${resolved.label} is already wired (${relTarget})`);
-		}
+		if (manifest) applyLayoutPatches(cwd, manifest, scaffold);
 		if (gitignore !== "present") p.log.success(`${gitignore === "created" ? "Created" : "Updated"} .gitignore (ignoring .env)`);
 		nextStepsNote(setup.mode);
 		p.outro("Kizlo is ready 🎉");

package/dist/cli/presets/nextjs.js

@@ -1,5 +1,3 @@
-import { materializeTemplate } from "./template.js";
-
 //#region src/cli/presets/nextjs.ts
 const nextjs = {
 	id: "nextjs",
@@ -12,9 +10,7 @@ const nextjs = {
 	},
 	baseUrlEnvKey: "NEXT_PUBLIC_KIZLO_BACKEND_URL",
 	apiPath: "/api/kizlo",
-	scaffolds(ctx) {
-		return materializeTemplate("nextjs", ctx);
-	}
+	template: "nextjs"
 };
 
 //#endregion

package/dist/cli/presets/patch.js

@@ -1,4 +1,3 @@
-import { TEMPLATE_PATCHES } from "./generated/templates.js";
 import path from "node:path";
 import fs from "node:fs";
 import { builders, detectCodeFormat, generateCode, parseModule } from "magicast";
@@ -28,26 +27,7 @@ function resolvePatchTargetPath(cwd, relPath) {
 		if (fs.existsSync(candidate)) return candidate;
 	}
 }
-/** The Kizlo-wiring patches for a framework (files init merges into rather than writes). */
-function templatePatches(framework) {
-	return TEMPLATE_PATCHES[framework] ?? [];
-}
-/** Substitute the path/import tokens for a patch against the project's real directories. */
-function resolvePatch(patch, ctx) {
-	const relPath = patch.tokenizedFile.replaceAll("{{kizloDir}}", ctx.kizloDir).replaceAll("{{appDir}}", ctx.appDir);
-	const fromDir = path.posix.dirname(relPath);
-	const imports = patch.imports.map((imp) => ({
-		module: imp.module.replaceAll("{{serverImport}}", ctx.serverImport(fromDir)),
-		names: imp.names
-	}));
-	return {
-		label: patch.label,
-		relPath,
-		imports,
-		exports: patch.exports
-	};
-}
-/** Whether a patch actually modified the file (vs. a no-op / kept outcome). */
+/** Whether a patch actually modified the file (vs. a no-op / already-wired outcome). */
 function patchChanged(changes) {
 	return Boolean(changes.addedImports.length || changes.addedExports.length || changes.replacedExports.length);
 }
@@ -69,15 +49,18 @@ function sameExpr(a, b) {
 }
 /**
 * Merge a resolved patch into `source` by parsing it with magicast (a real TS/JS/JSX parser via Babel,
-* so declarations are bounded exactly — never by a text heuristic). Imports and absent exports are
-* added; an export the file already defines is replaced surgically when `replaceConflicts` is set, else
-* kept. A static Next counterpart (`metadata` for `generateMetadata`) is dropped as part of a replace.
-* Idempotent: an export whose current value already equals ours is left untouched.
+* so declarations are bounded exactly — never by a text heuristic). Missing imports are added; each
+* export is upserted — set with `builders`, which replaces it if present and adds it if not — and a
+* static Next counterpart (`metadata` for `generateMetadata`) is dropped as part of a replace. The
+* upsert is deliberate replace-always: we cannot distinguish a user's own `generateMetadata` from a
+* stale copy of ours, and those values come from WordPress (edited in wp-admin, not the file), so the
+* export body isn't meant to be hand-customized. Idempotent: an export already equal to ours is left
+* untouched, so re-running never churns the file.
 *
-* Throws if the target cannot be parsed or regenerated. Callers must NOT swallow that — a file we can't
-* parse is one we must not guess at, so wiring stops rather than writing a corrupted file.
+* Throws if the target cannot be parsed or regenerated. Callers must NOT swallow that — a file we
+* can't parse is one we must not guess at, so wiring falls back to a printed instruction instead.
 */
-function applyPatchToSource(source, patch, opts) {
+function applyPatchToSource(source, patch) {
 	const format = detectCodeFormat(source);
 	const mod = parseModule(source, {
 		sourceFileName: "layout.tsx",
@@ -86,8 +69,7 @@ function applyPatchToSource(source, patch, opts) {
 	const changes = {
 		addedImports: [],
 		addedExports: [],
-		replacedExports: [],
-		keptExports: []
+		replacedExports: []
 	};
 	for (const imp of patch.imports) for (const name of imp.names) {
 		if (mod.imports.$items.some((item) => item.from === imp.module && item.imported === name)) continue;
@@ -101,20 +83,12 @@ function applyPatchToSource(source, patch, opts) {
 		const exportNames = Object.keys(mod.exports);
 		if (exportNames.includes(exp.name)) {
 			if (sameExpr(generateCode(mod.exports[exp.name]).code, exp.value)) continue;
-			if (!opts.replaceConflicts) {
-				changes.keptExports.push(exp.name);
-				continue;
-			}
 			mod.exports[exp.name] = builders.raw(exp.value);
 			changes.replacedExports.push(exp.name);
 			continue;
 		}
 		const counterpart = staticCounterpart(exp.name);
 		if (counterpart && exportNames.includes(counterpart)) {
-			if (!opts.replaceConflicts) {
-				changes.keptExports.push(exp.name);
-				continue;
-			}
 			delete mod.exports[counterpart];
 			mod.exports[exp.name] = builders.raw(exp.value);
 			changes.replacedExports.push(exp.name);
@@ -128,6 +102,20 @@ function applyPatchToSource(source, patch, opts) {
 		changes
 	};
 }
+/**
+* Render a resolved patch as source the user can paste in, for the printed fallback when the target
+* can't be resolved or parsed. The same declared payload the confident apply upserts, so what we tell
+* the user to add never drifts from what we would have written.
+*/
+function renderPatchCode(patch) {
+	const imports = patch.imports.map((imp) => `import { ${imp.names.join(", ")} } from "${imp.module}"`);
+	const exports = patch.exports.map((exp) => `export const ${exp.name} = ${exp.value}`);
+	return `${[
+		...imports,
+		"",
+		...exports
+	].join("\n")}\n`;
+}
 
 //#endregion
-export { applyPatchToSource, patchChanged, resolvePatch, resolvePatchTargetPath, templatePatches };
+export { applyPatchToSource, patchChanged, renderPatchCode, resolvePatchTargetPath };

package/dist/cli/presets/source.js

@@ -0,0 +1,50 @@
+import path from "node:path";
+import fs from "node:fs";
+import os from "node:os";
+import { downloadTemplate } from "giget";
+
+//#region src/cli/presets/source.ts
+/** GitHub repo the templates are fetched from. */
+const TEMPLATE_REPO = "github:kizlo-io/kizlo";
+/**
+* Resolve where a template is fetched from. Defaults to the templates on the repo's default branch:
+* the template is decoupled from the CLI version — it declares its own `kizlo` dependency — so there
+* is no tag to match and no release to cut. `KIZLO_TEMPLATE_LOCAL_DIR` points at a local `templates/`
+* directory so development (and `create`/`init` tests) never touch the network.
+*/
+function templateSource(template) {
+	const localDir = process.env.KIZLO_TEMPLATE_LOCAL_DIR;
+	if (localDir) return { local: path.resolve(localDir, template) };
+	return { remote: `${TEMPLATE_REPO}/templates/${template}` };
+}
+/**
+* Get the template as a readable directory both `create` and `init` can copy from or read. With
+* `KIZLO_TEMPLATE_LOCAL_DIR` set it's the local folder (returned as-is, cleanup is a no-op). Otherwise
+* it's downloaded once into a fresh temp directory the caller cleans up. The single fetch path shared
+* by both commands, so they can never source different bytes.
+*/
+async function fetchTemplate(template) {
+	const source = templateSource(template);
+	if (source.local) {
+		if (!fs.existsSync(source.local)) throw new Error(`Local template not found: ${source.local}`);
+		return {
+			dir: source.local,
+			cleanup: () => {}
+		};
+	}
+	const dir = fs.mkdtempSync(path.join(os.tmpdir(), "kizlo-template-"));
+	await downloadTemplate(source.remote, {
+		dir,
+		forceClean: true
+	});
+	return {
+		dir,
+		cleanup: () => fs.rmSync(dir, {
+			recursive: true,
+			force: true
+		})
+	};
+}
+
+//#endregion
+export { fetchTemplate };

package/dist/cli/presets/template.js

@@ -1,8 +1,59 @@
-import { TEMPLATE_SUBSETS } from "./generated/templates.js";
+import { resolvePatchTargetPath } from "./patch.js";
+import z from "zod/v4";
 import path from "node:path";
+import fs from "node:fs";
 
 //#region src/cli/presets/template.ts
-/** Role → the human label init uses in prompts and logs. Mirrors the old hardcoded labels. */
+/**
+* The template's `template.json`. It is the single declaration of which files Kizlo lays onto a
+* project and how each is applied — the same engine drives both `create` (onto a fresh app the
+* framework CLI just bootstrapped) and `init` (onto the user's existing project). Every entry is one
+* of a small closed set — deliberately no "patch an arbitrary source file" kind, so a dangerous
+* strategy is unrepresentable:
+*
+* - `own` — a whole file Kizlo writes, adapted to the project's directories and written through the
+*   overwrite policy. `wiring`-scope files (the default) are laid down by both commands; `starter`
+*   demo files are laid down only by `create` (see {@link ownEntries}).
+* - `patch` — a partial injection into a file the framework owns (the root layout's SEO exports).
+*   Both commands try a confident apply, otherwise print the payload with placement instructions.
+*/
+const tokensSchema = z.object({
+	kizloDir: z.string(),
+	appDir: z.string(),
+	alias: z.string()
+});
+const ownSchema = z.object({
+	kind: z.literal("own"),
+	role: z.string(),
+	path: z.string(),
+	scope: z.enum(["wiring", "starter"]).optional()
+});
+const patchSchema = z.object({
+	kind: z.literal("patch"),
+	role: z.string(),
+	label: z.string(),
+	path: z.string(),
+	imports: z.array(z.object({
+		module: z.string(),
+		names: z.array(z.string())
+	})),
+	exports: z.array(z.object({
+		name: z.string(),
+		value: z.string()
+	}))
+});
+const bootstrapSchema = z.object({
+	initializer: z.string(),
+	flags: z.array(z.string()).default([])
+});
+const manifestSchema = z.object({
+	framework: z.string(),
+	kizloVersion: z.string().optional(),
+	bootstrap: bootstrapSchema.optional(),
+	tokens: tokensSchema,
+	files: z.array(z.discriminatedUnion("kind", [ownSchema, patchSchema]))
+});
+/** Role → the human label init uses in prompts and logs. */
 const ROLE_LABELS = {
 	"server-entry": "Kizlo server instance",
 	client: "Browser client",
@@ -10,27 +61,112 @@ const ROLE_LABELS = {
 	robots: "robots.txt route",
 	sitemap: "sitemap route",
 	"sitemap-redirect": "sitemap.xml redirect route",
-	manifest: "web manifest route"
+	manifest: "web manifest route",
+	"home-page": "home page",
+	"blog-post": "blog post page",
+	styles: "global styles"
 };
+/** Read and validate the template's manifest from a fetched template directory. */
+function readManifest(templateDir) {
+	const manifestPath = path.join(templateDir, "template.json");
+	if (!fs.existsSync(manifestPath)) throw new Error(`Template manifest not found at ${manifestPath}`);
+	return manifestSchema.parse(JSON.parse(fs.readFileSync(manifestPath, "utf8")));
+}
 /**
-* Turn a framework's extracted template subset into the {@link ScaffoldFile}s init writes, by
-* substituting the tokens the extractor left behind: the path prefixes (`{{kizloDir}}`, `{{appDir}}`)
-* with the project's real directories, and `{{serverImport}}` with the import specifier resolved for
-* each file's location (tsconfig alias or relative). The single source of these bodies is the
-* template folder, so init and `create` can never drift.
+* The `own` files to scaffold. By default only `wiring` files (the Kizlo plumbing) — this is what
+* `init` lays onto an existing project, so it never touches the user's own pages. With
+* `includeStarter`, demo `starter` files are added too, which is what `create` lays onto a fresh app.
 */
-function materializeTemplate(framework, ctx) {
-	return (TEMPLATE_SUBSETS[framework] ?? []).map((file) => {
-		const relPath = file.tokenizedPath.replaceAll("{{kizloDir}}", ctx.kizloDir).replaceAll("{{appDir}}", ctx.appDir);
-		const fromDir = path.posix.dirname(relPath);
-		const contents = file.body.replaceAll("{{serverImport}}", ctx.serverImport(fromDir));
-		return {
-			label: ROLE_LABELS[file.role] ?? file.role,
-			relPath,
-			contents
-		};
-	});
+function ownEntries(manifest, opts = {}) {
+	return manifest.files.filter((file) => file.kind === "own" && (opts.includeStarter || file.scope !== "starter"));
+}
+function patchEntries(manifest) {
+	return manifest.files.filter((file) => file.kind === "patch");
+}
+/** The specifier the template's files use to reach the server entry, e.g. `@/lib/kizlo/server`. */
+function serverImportSpecifier(tokens) {
+	const withoutSrc = tokens.kizloDir.replace(/^src\//, "");
+	return `${tokens.alias.replace(/\/+$/, "")}/${withoutSrc}/server`;
+}
+/**
+* Adapt a template path prefix (`src/app/...`, `src/lib/kizlo/...`) to the project's real directories.
+* Only the leading token dir is swapped; the rest of the path is preserved verbatim.
+*/
+function adaptTemplatePath(relPath, tokens, ctx) {
+	const normalized = relPath.split(path.sep).join("/");
+	if (normalized === tokens.appDir || normalized.startsWith(`${tokens.appDir}/`)) return `${ctx.appDir}${normalized.slice(tokens.appDir.length)}`;
+	if (normalized === tokens.kizloDir || normalized.startsWith(`${tokens.kizloDir}/`)) return `${ctx.kizloDir}${normalized.slice(tokens.kizloDir.length)}`;
+	return normalized;
+}
+/**
+* Turn an `own` manifest entry into the {@link ScaffoldFile} init writes: read the template's real
+* file, rewrite its path prefix to the project's directories, and swap the server-entry import
+* specifier for the one resolved at the file's new location (tsconfig alias or relative). The swap is
+* surgical — it replaces the exact specifier the template uses, not a loose directory substring — so
+* an unrelated occurrence can't be corrupted. This is the job the old build-time extractor did; it
+* moves to runtime and stays as precise.
+*/
+function adaptOwnFile(templateDir, entry, tokens, ctx) {
+	const abs = path.join(templateDir, entry.path);
+	if (!fs.existsSync(abs)) throw new Error(`Template file "${entry.path}" is listed in the manifest but does not exist in the template.`);
+	const body = fs.readFileSync(abs, "utf8");
+	const relPath = adaptTemplatePath(entry.path, tokens, ctx);
+	const fromDir = path.posix.dirname(relPath);
+	const contents = body.split(serverImportSpecifier(tokens)).join(ctx.serverImport(fromDir));
+	return {
+		label: ROLE_LABELS[entry.role] ?? entry.role,
+		relPath,
+		contents
+	};
+}
+/** Substitute the path/import tokens for a patch against the project's real directories. */
+function resolvePatch(entry, tokens, ctx) {
+	const relPath = adaptTemplatePath(entry.path, tokens, ctx);
+	const fromDir = path.posix.dirname(relPath);
+	const imports = entry.imports.map((imp) => ({
+		module: imp.module.replaceAll("{{serverImport}}", ctx.serverImport(fromDir)),
+		names: imp.names
+	}));
+	return {
+		label: entry.label,
+		relPath,
+		imports,
+		exports: entry.exports
+	};
+}
+const LAYOUT_FILE = /^layout\.(tsx|jsx|ts|js|mjs|cjs)$/;
+/** A root layout is the one that renders `<html>` — its identity, not its path. */
+const RENDERS_HTML = /<html[\s/>]/;
+/** Every file under `dir`, recursively (files only). Missing dir yields nothing. */
+function walk(dir) {
+	if (!fs.existsSync(dir)) return [];
+	const out = [];
+	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+		const full = path.join(dir, entry.name);
+		if (entry.isDirectory()) out.push(...walk(full));
+		else out.push(full);
+	}
+	return out;
+}
+/**
+* Resolve the root layout by identity, not path. Try the manifest hint first; if it exists and
+* renders `<html>`, use it. Otherwise scan the App Router directory for a layout that renders `<html>`
+* and use it only when there is exactly one. On zero, many, or an unreadable file, return undefined so
+* the caller prints the wiring for the user to place. Never guesses.
+*/
+function findRootLayout(cwd, appDir, hintRelPath) {
+	const hint = resolvePatchTargetPath(cwd, hintRelPath);
+	if (hint && rendersHtml(hint)) return hint;
+	const matches = walk(path.join(cwd, appDir)).filter((file) => LAYOUT_FILE.test(path.basename(file)) && rendersHtml(file));
+	return matches.length === 1 ? matches[0] : void 0;
+}
+function rendersHtml(file) {
+	try {
+		return RENDERS_HTML.test(fs.readFileSync(file, "utf8"));
+	} catch {
+		return false;
+	}
 }
 
 //#endregion
-export { materializeTemplate };
+export { adaptOwnFile, findRootLayout, ownEntries, patchEntries, readManifest, resolvePatch };

package/dist/cli/utils.js

@@ -2,7 +2,7 @@ import { log } from "./daemon/logger.js";
 import { PortInUseError, resolveHostPort } from "./wp/ports.js";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import fs from "node:fs";
 import * as p from "@clack/prompts";
 
@@ -107,6 +107,31 @@ function detectPackageManager(cwd) {
 	if (fs.existsSync(path.join(cwd, "bun.lockb")) || fs.existsSync(path.join(cwd, "bun.lock"))) return "bun";
 	return "npm";
 }
+/**
+* The package manager that invoked the current process, read from `npm_config_user_agent`
+* (e.g. `pnpm/9.0.0 npm/? node/v20`). Used to pre-select the most likely choice when a fresh
+* project has no lockfile to detect from. Returns undefined when the agent is absent or unknown.
+*/
+function detectInvokingPackageManager() {
+	const name = process.env.npm_config_user_agent?.split("/")[0];
+	return name === "pnpm" || name === "yarn" || name === "bun" || name === "npm" ? name : void 0;
+}
+/**
+* Whether `command` resolves to a runnable executable, probed with `--version`. Used to hide or
+* disable package-manager choices the user can't actually run. A non-zero exit or a spawn error
+* (the binary isn't on PATH) both count as unavailable.
+*/
+function isCommandAvailable(command) {
+	const result = spawnSync(command, ["--version"], {
+		stdio: "ignore",
+		shell: process.platform === "win32"
+	});
+	return !result.error && result.status === 0;
+}
+/** The package managers currently installed on the host, in the given display order. */
+function availablePackageManagers(order) {
+	return order.filter((pm) => isCommandAvailable(pm));
+}
 function addDependencyArgs(pm, pkg) {
 	if (pm === "npm") return [
 		"npm",
@@ -119,6 +144,42 @@ function addDependencyArgs(pm, pkg) {
 		pkg
 	];
 }
+/** The argv to install a project's dependencies with `pm` — every supported manager spells it `<pm> install`. */
+function installArgs(pm) {
+	return [pm, "install"];
+}
+/**
+* The argv to run a framework's `create-*` initializer through a package manager, e.g.
+* `pnpm create next-app@latest my-app --ts …`. The mechanics differ per manager: npm forwards
+* flags to the initializer only after a `--` separator, and `yarn create` resolves the latest
+* version itself so the `@latest` tag is dropped. `flags` are the initializer's own options.
+*/
+function frameworkCreateArgs(pm, initializer, name, flags) {
+	switch (pm) {
+		case "npm": return [
+			"npm",
+			"create",
+			initializer,
+			name,
+			"--",
+			...flags
+		];
+		case "yarn": return [
+			"yarn",
+			"create",
+			initializer.replace(/@latest$/, ""),
+			name,
+			...flags
+		];
+		default: return [
+			pm,
+			"create",
+			initializer,
+			name,
+			...flags
+		];
+	}
+}
 function runCommand(args, cwd, stdio = "inherit") {
 	const [command, ...rest] = args;
 	if (!command) return false;
@@ -128,6 +189,45 @@ function runCommand(args, cwd, stdio = "inherit") {
 		shell: process.platform === "win32"
 	}).status === 0;
 }
+/**
+* Async sibling of {@link runCommand}: runs a command without blocking the event loop, so a clack
+* spinner can keep animating while it works (a synchronous `spawnSync` would freeze it on the first
+* frame). Resolves whether it exited cleanly; a spawn error (binary off PATH) resolves false.
+*/
+function runCommandAsync(args, cwd, stdio = "inherit") {
+	const [command, ...rest] = args;
+	if (!command) return Promise.resolve(false);
+	return new Promise((resolve$1) => {
+		const child = spawn(command, rest, {
+			cwd,
+			stdio,
+			shell: process.platform === "win32"
+		});
+		child.on("error", () => resolve$1(false));
+		child.on("close", (code) => resolve$1(code === 0));
+	});
+}
+/**
+* Run a command capturing its combined output instead of streaming it, for a step that should stay
+* quiet on success but whose logs are worth surfacing when it fails (e.g. the framework's scaffolder
+* behind a spinner). Returns whether it succeeded and the trimmed stdout+stderr.
+*/
+function runCommandCaptured(args, cwd) {
+	const [command, ...rest] = args;
+	if (!command) return {
+		ok: false,
+		output: ""
+	};
+	const result = spawnSync(command, rest, {
+		cwd,
+		encoding: "utf8",
+		shell: process.platform === "win32"
+	});
+	return {
+		ok: result.status === 0,
+		output: `${result.stdout ?? ""}${result.stderr ?? ""}`.trim()
+	};
+}
 function writeFileIfAbsent(filePath, contents) {
 	if (fs.existsSync(filePath)) return false;
 	fs.mkdirSync(path.dirname(filePath), { recursive: true });
@@ -263,4 +363,4 @@ function groupDefault(subCommandNames, run) {
 }
 
 //#endregion
-export { addDependencyArgs, detectImportAlias, detectPackageManager, ensureGitignored, envGroups, envKeysPresent, getVersion, groupDefault, loadEnvFiles, mergeEnv, pickStackPort, resolveModuleImport, runCommand, withSpinner, writeFileIfAbsent };
+export { addDependencyArgs, availablePackageManagers, detectImportAlias, detectInvokingPackageManager, detectPackageManager, ensureGitignored, envGroups, envKeysPresent, frameworkCreateArgs, getVersion, groupDefault, installArgs, loadEnvFiles, mergeEnv, pickStackPort, resolveModuleImport, runCommand, runCommandAsync, runCommandCaptured, withSpinner, writeFileIfAbsent };

package/dist/cli/wp/dev.js

@@ -6,8 +6,8 @@ import { createAdminAppPassword, seedUsers } from "./bootstrap.js";
 import { prepareByo } from "./byo.js";
 import { join } from "node:path";
 import { existsSync, rmSync } from "node:fs";
-import { randomBytes } from "node:crypto";
 import { networkInterfaces } from "node:os";
+import { randomBytes } from "node:crypto";
 
 //#region src/cli/wp/dev.ts
 /** A strong random admin password (144 bits, URL/JSON/CLI-safe characters). */

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.8.1";
+var version = "0.8.3";
 
 //#endregion
 export { version };

package/dist/router.d.ts

@@ -764,7 +764,7 @@ declare const ROUTER_MAP: {
         exclude?: string | number | (string | number)[] | undefined;
         include?: string | number | (string | number)[] | undefined;
         order?: "asc" | "desc" | undefined;
-        orderBy?: "id" | "slug" | "name" | "description" | "include" | "include_slugs" | "term_group" | "count" | undefined;
+        orderBy?: "count" | "id" | "slug" | "name" | "description" | "include" | "include_slugs" | "term_group" | undefined;
         hideEmpty?: string | boolean | undefined;
         parent?: string | number | undefined;
         post?: string | number | undefined;
@@ -976,7 +976,7 @@ declare const ROUTER_MAP: {
         exclude?: string | number | (string | number)[] | undefined;
         include?: string | number | (string | number)[] | undefined;
         order?: "asc" | "desc" | undefined;
-        orderBy?: "id" | "slug" | "name" | "description" | "include" | "include_slugs" | "term_group" | "count" | undefined;
+        orderBy?: "count" | "id" | "slug" | "name" | "description" | "include" | "include_slugs" | "term_group" | undefined;
         hideEmpty?: string | boolean | undefined;
         post?: string | number | undefined;
         slug?: string | string[] | undefined;
@@ -1135,7 +1135,7 @@ declare const ROUTER_MAP: {
     sitemaps: {
       list: Procedure<"internal", {}, {
         key: string;
-        type: "author" | "post_type" | "taxonomy";
+        type: "post_type" | "taxonomy" | "author";
         pages: number;
         lastmod: string;
       }[], DefinedErrorMapLike>;
@@ -1143,7 +1143,7 @@ declare const ROUTER_MAP: {
         origin: string;
         sitemaps: {
           key: string;
-          type: "author" | "post_type" | "taxonomy";
+          type: "post_type" | "taxonomy" | "author";
           pages: number;
           lastmod: string;
         }[];

package/dist/seo/schema.d.ts

@@ -108,17 +108,17 @@ declare const Seo: z.ZodObject<{
 type Seo = z.infer<typeof Seo>;
 declare const CONTENT_TYPES: readonly ["post_type", "taxonomy", "author"];
 declare const ContentType: z.ZodEnum<{
-  author: "author";
   post_type: "post_type";
   taxonomy: "taxonomy";
+  author: "author";
 }>;
 type ContentType = z.infer<typeof ContentType>;
 declare const Sitemap: z.ZodObject<{
   key: z.ZodString;
   type: z.ZodEnum<{
-    author: "author";
     post_type: "post_type";
     taxonomy: "taxonomy";
+    author: "author";
   }>;
   pages: z.ZodNumber;
   lastmod: z.ZodString;
@@ -127,9 +127,9 @@ type Sitemap = z.infer<typeof Sitemap>;
 declare const SitemapList: z.ZodArray<z.ZodObject<{
   key: z.ZodString;
   type: z.ZodEnum<{
-    author: "author";
     post_type: "post_type";
     taxonomy: "taxonomy";
+    author: "author";
   }>;
   pages: z.ZodNumber;
   lastmod: z.ZodString;
@@ -140,9 +140,9 @@ declare const SitemapIndex: z.ZodObject<{
   sitemaps: z.ZodArray<z.ZodObject<{
     key: z.ZodString;
     type: z.ZodEnum<{
-      author: "author";
       post_type: "post_type";
       taxonomy: "taxonomy";
+      author: "author";
     }>;
     pages: z.ZodNumber;
     lastmod: z.ZodString;
@@ -174,9 +174,9 @@ declare const SitemapUrlList: z.ZodArray<z.ZodObject<{
 type SitemapUrlList = z.infer<typeof SitemapUrlList>;
 declare const ListSitemapUrlInputBase: z.ZodObject<{
   type: z.ZodEnum<{
-    author: "author";
     post_type: "post_type";
     taxonomy: "taxonomy";
+    author: "author";
   }>;
   page: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodCoercedNumber<string | number>>>;
 }, z.core.$strip>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kizlo",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "type": "module",
   "description": "A headless WordPress framework for TypeScript.",
   "keywords": [

package/dist/cli/presets/generated/templates.js

@@ -1,59 +0,0 @@
-//#region src/cli/presets/generated/templates.ts
-const TEMPLATE_SUBSETS = { "nextjs": [
-	{
-		"role": "server-entry",
-		"tokenizedPath": "{{kizloDir}}/server/index.ts",
-		"body": "import { createKizlo } from \"kizlo/nextjs/server\"\n\nexport const { router, client, context, handler } = createKizlo()\n"
-	},
-	{
-		"role": "client",
-		"tokenizedPath": "{{kizloDir}}/client.ts",
-		"body": "import { createKizloClient } from \"kizlo/nextjs\"\nimport { contract } from \"./server/generated\"\n\nexport const client = createKizloClient(contract)\n"
-	},
-	{
-		"role": "api-route",
-		"tokenizedPath": "{{appDir}}/api/kizlo/[[...rest]]/route.ts",
-		"body": "import { handler } from \"{{serverImport}}\"\n\nexport { handler as GET, handler as POST, handler as PUT, handler as PATCH, handler as DELETE, handler as OPTIONS }\n"
-	},
-	{
-		"role": "robots",
-		"tokenizedPath": "{{appDir}}/robots.txt/route.ts",
-		"body": "import { createRobotsRoute } from \"kizlo/nextjs/server\"\nimport { client } from \"{{serverImport}}\"\n\n// Run on the edge: cheaper and faster than Node for a response this small.\nexport const runtime = \"edge\"\n\n// Vercel treats special metadata files like robots.txt and sitemap.xml as completely static\n// files at build time, bypassing normal Incremental Static Regeneration (ISR) and on-demand\n// revalidatePath rules.\n//\n// While your revalidation logic executes perfectly in a local Node.js server, Vercel uploads\n// these routes directly to its Edge CDN as immutable assets. Subsequent on-demand revalidation\n// triggers will successfully clear the Data Cache but fail to purge the CDN-level Edge cache\n// for that file.\n//\n// force-dynamic opts out of that static treatment so CMS edits show up; the WordPress call is\n// cached, so requests stay cheap.\nexport const dynamic = \"force-dynamic\"\n\nexport const GET = createRobotsRoute(client)\n"
-	},
-	{
-		"role": "sitemap",
-		"tokenizedPath": "{{appDir}}/sitemaps/[sitemap]/route.ts",
-		"body": "import { createSitemapRoute } from \"kizlo/nextjs/server\"\nimport { client } from \"{{serverImport}}\"\n\n// Run on the edge: cheaper and faster than Node for a response this small.\nexport const runtime = \"edge\"\n\n// Like robots.txt, Vercel bakes sitemap routes into immutable Edge CDN assets at build time,\n// bypassing ISR and on-demand revalidatePath. The index gets frozen with whatever WordPress\n// returned at build (often nothing, since the self-referential backend isn't reachable yet),\n// and revalidation can't purge that CDN copy.\n//\n// force-dynamic opts out of that static treatment. createSitemapRoute caches the WordPress calls\n// per sitemap and refreshes them on content changes (via revalidateTag), so requests stay cheap.\nexport const dynamic = \"force-dynamic\"\n\nexport const GET = createSitemapRoute(client)\n"
-	},
-	{
-		"role": "sitemap-redirect",
-		"tokenizedPath": "{{appDir}}/sitemap.xml/route.ts",
-		"body": "import { createSitemapRedirectRoute } from \"kizlo/nextjs/server\"\n\n// Many crawlers ignore robots.txt and probe the well-known /sitemap.xml directly. This route\n// permanently redirects (308) to the generated index at /sitemaps/index.xml. The response is a\n// fixed constant with no WordPress call or request input, so Next statically generates it at\n// build time (no runtime/edge function invoked per request).\nexport const GET = createSitemapRedirectRoute()\n"
-	},
-	{
-		"role": "manifest",
-		"tokenizedPath": "{{appDir}}/site.webmanifest/route.ts",
-		"body": "import { createManifestRoute } from \"kizlo/nextjs/server\"\nimport { client } from \"{{serverImport}}\"\n\n// Run on the edge: cheaper and faster than Node for a response this small.\nexport const runtime = \"edge\"\n\n// Like robots.txt, Vercel bakes this route into an immutable Edge CDN asset at build time,\n// bypassing ISR and on-demand revalidatePath. force-dynamic opts out of that static treatment\n// so brand-settings edits show up; createManifestRoute caches the WordPress call, so requests\n// stay cheap.\nexport const dynamic = \"force-dynamic\"\n\nexport const GET = createManifestRoute(client)\n"
-	}
-] };
-const TEMPLATE_PATCHES = { "nextjs": [{
-	"label": "root layout",
-	"tokenizedFile": "{{appDir}}/layout.tsx",
-	"imports": [{
-		"module": "kizlo/nextjs/server",
-		"names": ["createRootMetadata", "createRootViewport"]
-	}, {
-		"module": "{{serverImport}}",
-		"names": ["client"]
-	}],
-	"exports": [{
-		"name": "generateMetadata",
-		"value": "createRootMetadata(client)"
-	}, {
-		"name": "generateViewport",
-		"value": "createRootViewport(client)"
-	}]
-}] };
-
-//#endregion
-export { TEMPLATE_PATCHES, TEMPLATE_SUBSETS };