kizlo 0.8.0 → 0.8.2

package/dist/cli/commands/create.js

@@ -2,56 +2,64 @@ import { dockerAvailable } from "../wp/docker.js";
 import { detectPackageManager, getVersion } from "../utils.js";
 import { printBanner } from "../banner.js";
 import { getPreset } from "../presets/index.js";
+import { fetchTemplate } from "../presets/source.js";
+import { readManifest } from "../presets/template.js";
 import { collectConnectionInteractively, nextStepsNote, orCancel, setupLocalWordPress, syncRemote, validate, withApiPath, writeEnv } from "./_setup.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. When only one exists the template prompt auto-selects it.
+* preset that drives its WordPress setup.
 */
 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)"));
+/** Directory entries never copied into a scaffolded project — the internal manifest and build junk. */
+const SKIP_COPY = new Set([
+	"template.json",
+	"node_modules",
+	".next",
+	".turbo",
+	".git"
+]);
 /**
-* 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.
-*/
-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()}`}` };
-}
-/**
-* 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.
+* Copy the template into `dir`, then make it a standalone project: name the package after the
+* project folder and resolve the monorepo-only `workspace:*` Kizlo dependency to the version the
+* template declares (`kizloVersion` in its manifest, stamped at release), falling back to the running
+* CLI's version. The version the project runs is the template's to decide, not a moving `latest` tag.
+* The template's `template.json` is an internal input, so it's left out of the copy — as is
+* local build junk (`node_modules`, `.next`, …) that only exists on the `KIZLO_TEMPLATE_LOCAL_DIR` path.
 */
 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
-	});
-	fs.rmSync(path.join(dir, "kizlo.template.json"), { force: true });
+	const { dir: src, cleanup } = await fetchTemplate(template);
+	let kizloVersion;
+	try {
+		kizloVersion = readManifest(src).kizloVersion ?? `^${getVersion()}`;
+		fs.cpSync(src, dir, {
+			recursive: true,
+			filter: (from) => !SKIP_COPY.has(path.basename(from))
+		});
+	} finally {
+		cleanup();
+	}
 	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. Check the template name and your network connection, then try again.`);
+	}
 	const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
 	pkg.name = name;
-	if (pkg.dependencies?.kizlo === "workspace:*") pkg.dependencies.kizlo = `^${getVersion()}`;
+	if (pkg.dependencies?.kizlo === "workspace:*") pkg.dependencies.kizlo = kizloVersion;
 	fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, "	")}\n`);
 }
 const create = defineCommand({
@@ -83,8 +91,7 @@ const create = defineCommand({
 				process.exit(1);
 			}
 			template = requested;
-		} else if (TEMPLATES.length === 1) template = TEMPLATES[0];
-		else template = orCancel(await p.select({
+		} else template = orCancel(await p.select({
 			message: "Template",
 			options: TEMPLATES.map((id) => ({
 				value: id,

package/dist/cli/commands/init.js

@@ -2,9 +2,11 @@ import { dockerAvailable } from "../wp/docker.js";
 import { addDependencyArgs, detectImportAlias, detectPackageManager, ensureGitignored, getVersion, loadEnvFiles, resolveModuleImport, runCommand, writeFileIfAbsent } from "../utils.js";
 import { printBanner } from "../banner.js";
 import { PRESETS, detectPreset, getPreset } from "../presets/index.js";
+import { fetchTemplate } from "../presets/source.js";
+import { applyPatchToSource, patchChanged, renderPatchCode } from "../presets/patch.js";
+import { adaptOwnFile, findRootLayout, ownEntries, patchEntries, readManifest, resolvePatch } 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 path from "node:path";
 import fs from "node:fs";
 import { defineCommand } from "citty";
@@ -108,6 +110,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 +205,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 +226,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);
@@ -214,7 +256,18 @@ const init = defineCommand({
 			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,
@@ -228,42 +281,37 @@ const init = defineCommand({
 		writeFileIfAbsent(path.join(cwd, generatedDirRel, "index.ts"), CONTRACT_BARREL);
 		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)`);
+		const manualSteps = [];
+		for (const entry of manifest ? 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, abs);
-			const src = fs.readFileSync(abs, "utf8");
-			let text;
-			let changes;
+			const relTarget = path.relative(cwd, target);
+			const src = fs.readFileSync(target, "utf8");
+			let applied;
 			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 }));
+				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(abs, text);
+				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(", ")}`);
-			}
-			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})`);
+			} 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>)`);
 		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,51 @@
-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 are Kizlo wiring
+* and how each is applied. 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. Its path is authoritative; `create` copies it and `init`
+*   adapts + writes it through the overwrite policy.
+* - `patch` — a partial injection into a file the user owns (the root layout's SEO exports). `init`
+*   tries a confident apply, otherwise prints the payload with placement instructions. `create` never
+*   patches — its own template files already carry the wiring.
+*/
+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()
+});
+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 manifestSchema = z.object({
+	framework: z.string(),
+	kizloVersion: z.string().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",
@@ -12,25 +55,102 @@ const ROLE_LABELS = {
 	"sitemap-redirect": "sitemap.xml redirect route",
 	manifest: "web manifest route"
 };
+/** 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")));
+}
+function ownEntries(manifest) {
+	return manifest.files.filter((file) => file.kind === "own");
+}
+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`;
+}
 /**
-* 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.
+* 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 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 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/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.0";
+var version = "0.8.2";
 
 //#endregion
 export { version };

package/dist/router.d.ts

@@ -179,7 +179,7 @@ declare const ROUTER_MAP: {
         include?: string | number | (string | number)[] | undefined;
         offset?: string | number | undefined;
         order?: "asc" | "desc" | undefined;
-        orderby?: "date" | "id" | "slug" | "parent" | "title" | "author" | "include" | "modified" | "relevance" | "include_slugs" | undefined;
+        orderby?: "id" | "date" | "slug" | "parent" | "title" | "author" | "include" | "modified" | "relevance" | "include_slugs" | undefined;
         searchColumns?: ("post_title" | "post_content" | "post_excerpt")[] | undefined;
         slug?: string | string[] | undefined;
         taxRelation?: "AND" | "OR" | undefined;
@@ -507,7 +507,7 @@ declare const ROUTER_MAP: {
         include?: string | number | (string | number)[] | undefined;
         offset?: string | number | undefined;
         order?: "asc" | "desc" | undefined;
-        orderby?: "date" | "id" | "slug" | "parent" | "title" | "author" | "include" | "modified" | "relevance" | "include_slugs" | "menu_order" | undefined;
+        orderby?: "id" | "date" | "slug" | "parent" | "title" | "author" | "include" | "modified" | "relevance" | "include_slugs" | "menu_order" | undefined;
         searchColumns?: ("post_title" | "post_content" | "post_excerpt")[] | undefined;
         slug?: string | string[] | undefined;
         parent?: string | number | (string | number)[] | undefined;
@@ -1186,7 +1186,7 @@ declare const ROUTER_MAP: {
           include?: string | number | (string | number)[] | undefined;
           offset?: string | number | undefined;
           order?: "asc" | "desc" | undefined;
-          orderby?: "date" | "id" | "slug" | "parent" | "title" | "author" | "include" | "relevance" | "include_slugs" | "menu_order" | undefined;
+          orderby?: "id" | "date" | "slug" | "parent" | "title" | "author" | "include" | "relevance" | "include_slugs" | "menu_order" | undefined;
           searchColumns?: ("post_title" | "post_content" | "post_excerpt")[] | undefined;
           slug?: string | string[] | undefined;
           taxRelation?: "AND" | "OR" | undefined;
@@ -1265,7 +1265,7 @@ declare const ROUTER_MAP: {
           include?: string | number | (string | number)[] | undefined;
           offset?: string | number | undefined;
           order?: "asc" | "desc" | undefined;
-          orderby?: "date" | "id" | "slug" | "parent" | "title" | "author" | "include" | "relevance" | "include_slugs" | "menu_order" | undefined;
+          orderby?: "id" | "date" | "slug" | "parent" | "title" | "author" | "include" | "relevance" | "include_slugs" | "menu_order" | undefined;
           searchColumns?: ("post_title" | "post_content" | "post_excerpt")[] | undefined;
           slug?: string | string[] | undefined;
           taxRelation?: "AND" | "OR" | undefined;
@@ -1414,7 +1414,7 @@ declare const ROUTER_MAP: {
         include?: string | number | (string | number)[] | undefined;
         offset?: string | number | undefined;
         order?: "asc" | "desc" | undefined;
-        orderby?: "date" | "id" | "parent" | "post" | "include" | undefined;
+        orderby?: "id" | "date" | "parent" | "post" | "include" | undefined;
         parent?: string | number | (string | number)[] | undefined;
         parentExclude?: string | number | (string | number)[] | undefined;
         post?: string | number | (string | number)[] | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kizlo",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "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 };