kizlo 0.11.0 → 0.12.0

package/dist/astro/server.d.ts

@@ -0,0 +1,9 @@
+import { WEB_MANIFEST_ROUTE } from "../brand/manifest.js";
+import { renderJsonLd } from "../seo/utils.js";
+import { KizloServerOptions, createKizlo } from "../integrations/astro/kizlo.server.js";
+import { AstroRoute, AstroRouteContext, getServerBaseUrl } from "../integrations/astro/utils.js";
+import { createManifestRoute } from "../integrations/astro/manifest.js";
+import { PageHead, RootHead, ThemeColor, resolvePageHead, resolveRootHead } from "../integrations/astro/metadata.js";
+import { createRobotsRoute } from "../integrations/astro/robots.js";
+import { createSitemapRedirectRoute, createSitemapRoute } from "../integrations/astro/sitemap.js";
+export { AstroRoute, AstroRouteContext, KizloServerOptions, PageHead, RootHead, ThemeColor, WEB_MANIFEST_ROUTE, createKizlo, createManifestRoute, createRobotsRoute, createSitemapRedirectRoute, createSitemapRoute, getServerBaseUrl, renderJsonLd, resolvePageHead, resolveRootHead };

package/dist/astro/server.js

@@ -0,0 +1,10 @@
+import { WEB_MANIFEST_ROUTE } from "../brand/manifest.js";
+import { renderJsonLd } from "../seo/utils.js";
+import { getServerBaseUrl } from "../integrations/astro/utils.js";
+import { createKizlo } from "../integrations/astro/kizlo.server.js";
+import { createManifestRoute } from "../integrations/astro/manifest.js";
+import { resolvePageHead, resolveRootHead } from "../integrations/astro/metadata.js";
+import { createRobotsRoute } from "../integrations/astro/robots.js";
+import { createSitemapRedirectRoute, createSitemapRoute } from "../integrations/astro/sitemap.js";
+
+export { WEB_MANIFEST_ROUTE, createKizlo, createManifestRoute, createRobotsRoute, createSitemapRedirectRoute, createSitemapRoute, getServerBaseUrl, renderJsonLd, resolvePageHead, resolveRootHead };

package/dist/astro.d.ts

@@ -0,0 +1,2 @@
+import { KizloClientOptions, createKizloClient } from "./integrations/astro/kizlo.client.js";
+export { KizloClientOptions, createKizloClient };

package/dist/astro.js

@@ -0,0 +1,3 @@
+import { createKizloClient } from "./integrations/astro/kizlo.client.js";
+
+export { createKizloClient };

package/dist/cli/commands/_setup.js

@@ -17,13 +17,13 @@ import getPort, { portNumbers } from "get-port";
 
 //#region src/cli/commands/_setup.ts
 /**
-* The resolved `.env` key names the scaffold writes: the template's declared `env` when it has one,
-* else the preset's built-in `envKeys` (the generic `base` preset), else the {@link DEFAULT_ENV_KEYS}
-* fallback for an in-repo template before the first stamped release. Threaded into `managedEnv`,
-* `writeEnv`, and `collectConnectionFromEnv` so the scaffold writes the names the pinned runtime reads.
+* The resolved `.env` key names the scaffold writes: the template's declared `env` when it has one, else
+* the {@link DEFAULT_ENV_KEYS} fallback — for an in-repo template before the first stamped release, and
+* for the base no-template fallback (which has no manifest). Threaded into `managedEnv`, `writeEnv`, and
+* `collectConnectionFromEnv` so the scaffold writes the names the pinned runtime reads.
 */
-function resolveEnvKeys(preset, manifest) {
-	return manifest?.env ?? preset.envKeys ?? DEFAULT_ENV_KEYS;
+function resolveEnvKeys(manifest) {
+	return manifest?.env ?? DEFAULT_ENV_KEYS;
 }
 /** Remote connection keys — what a real deploy needs, and what `.env.example` always lists. */
 function remoteKeys(envKeys) {
@@ -135,11 +135,11 @@ function pickAppPort() {
 * `create` scaffolds a brand-new app that has no public URL yet, so it defaults to the local dev
 * origin and lets the user fill in production later.
 */
-async function collectConnectionInteractively(preset, opts = {}) {
+async function collectConnectionInteractively(apiPath, opts = {}) {
 	let siteUrl;
 	let baseUrl;
 	if (opts.baseUrl !== void 0) baseUrl = opts.baseUrl;
-	else if (preset.apiPath) baseUrl = orCancel(await p.text({
+	else if (apiPath) baseUrl = orCancel(await p.text({
 		message: "Public app URL",
 		placeholder: "https://your-app.com",
 		validate: validate(urlString)

package/dist/cli/commands/create.js

@@ -1,6 +1,5 @@
 import { availablePackageManagers, detectInvokingPackageManager, ensureGitignored, frameworkCreateArgs, installArgs, runCommandAsync, runCommandCaptured } from "../utils.js";
-import { getPreset } from "../presets/index.js";
-import { fetchTemplate } from "../presets/source.js";
+import { fetchRegistry, listTemplates, resolveRegistry } from "../presets/source.js";
 import { adaptFile, changesFor, fileEntries, minCliError, patchEntries, readManifest, resolveDependencies } from "../presets/template.js";
 import { collectConnectionInteractively, nextStepsLines, orCancel, pickAppPort, readEnvExample, resolveEnvKeys, setupLocalWordPress, syncRemote, validate, withApiPath, writeEnv } from "./_setup.js";
 import { applyLayoutPatches, buildScaffoldContext, kizloConfigTemplate, reportScaffold, scaffoldFile, writeGeneratedContract } from "./_wiring.js";
@@ -11,15 +10,30 @@ import { defineCommand } from "citty";
 import * as p from "@clack/prompts";
 
 //#region src/cli/commands/create.ts
+/** The final path segment of a project name — the app folder itself; everything before it is where it lands. */
+function folderSegment(value) {
+	const segments = value.replace(/\\/g, "/").split("/").filter(Boolean);
+	return segments[segments.length - 1] ?? "";
+}
 /**
-* The templates `create` can scaffold from. Each id is both the `templates/<id>` folder and the
-* preset that drives its WordPress setup and framework bootstrap.
+* Tidy the entered name/path for both the target dir and the display: trim, drop a leading `./`, and drop a
+* trailing separator, so `cd`, the spinner, and the warning lines read as `templates/my-app`, not
+* `./templates/my-app/`. Preserves `../` and absolute paths (only a leading `./` is redundant).
 */
-const TEMPLATES = ["nextjs"];
-function isTemplate(value) {
-	return TEMPLATES.includes(value);
+function normalizeProjectName(value) {
+	return value.trim().replace(/^\.\/+/, "").replace(/[/\\]+$/, "");
 }
-const projectName = validate(z.string().trim().min(1, "Required").refine((value) => !value.startsWith(".") && !value.includes("/") && !value.includes("\\"), "Enter a folder name (letters, numbers, dashes)"));
+/**
+* A project name may be a bare folder (`my-app`) or a path to scaffold somewhere other than the current
+* dir — relative (`apps/my-app`, `../my-app`) or absolute (`/srv/my-app`). Only the last segment is the
+* app folder, so that's what's validated as a name; the parent dirs (which may not exist yet) are created
+* by the framework's own CLI. `.`/`..` as the final segment, or a name with no real segment, is rejected.
+*/
+const projectNameSchema = z.string().trim().min(1, "Required").refine((value) => {
+	const base = folderSegment(value);
+	return base.length > 0 && base !== "." && base !== ".." && /^[A-Za-z0-9._-]+$/.test(base);
+}, "The app folder (last path segment) can only contain letters, numbers, dots, and dashes");
+const projectName = validate(projectNameSchema);
 /** Package managers `create` can wire the getting-started steps for, in display order. */
 const PACKAGE_MANAGERS = [
 	"pnpm",
@@ -37,17 +51,25 @@ function recordDependencies(dir, manifest) {
 	const pkgPath = path.join(dir, "package.json");
 	const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
 	const { dependencies, devDependencies } = resolveDependencies(manifest);
-	pkg.dependencies = {
+	pkg.dependencies = sortDependencies({
 		...pkg.dependencies,
 		...dependencies
-	};
-	if (Object.keys(devDependencies).length) pkg.devDependencies = {
+	});
+	if (Object.keys(devDependencies).length) pkg.devDependencies = sortDependencies({
 		...pkg.devDependencies,
 		...devDependencies
-	};
+	});
 	fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, "	")}\n`);
 }
 /**
+* Alphabetize a dependency map by package name. The framework CLI writes its deps sorted, but merging
+* Kizlo's pins on top appends them out of order — sherif flags unsorted dependency keys, so re-sort the
+* whole map before writing.
+*/
+function sortDependencies(deps) {
+	return Object.fromEntries(Object.entries(deps).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
+}
+/**
 * 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}
@@ -104,54 +126,75 @@ const create = defineCommand({
 		template: {
 			type: "positional",
 			required: false,
-			description: `Template to scaffold from (${TEMPLATES.join(", ")})`
+			description: "Template to scaffold from (discovered from the registry)"
 		},
 		name: {
 			type: "positional",
 			required: false,
-			description: "Project folder to create"
+			description: "Project folder to create — a bare name or a path (e.g. apps/my-app, ../my-app, /srv/my-app)"
+		},
+		source: {
+			type: "string",
+			description: "Where to scaffold from — a local dir or giget source, either a registry of templates or a single template (default: Kizlo's GitHub templates)"
 		}
 	},
 	async run({ args }) {
 		const cwd = process.cwd();
 		p.intro(`Let's create a new Kizlo application`);
+		const registry = resolveRegistry(args.source ? String(args.source) : void 0);
+		let fetchedRegistry;
+		try {
+			fetchedRegistry = await fetchRegistry(registry);
+		} catch (error) {
+			p.cancel(error instanceof Error ? error.message : String(error));
+			process.exit(1);
+		}
+		const templates = listTemplates(fetchedRegistry.dir);
+		if (templates.length === 0) {
+			fetchedRegistry.cleanup();
+			p.cancel(`No templates found in the registry (${registry.source}). Each template needs a template.json.`);
+			process.exit(1);
+		}
+		const cancelFrom = (message) => {
+			fetchedRegistry.cleanup();
+			p.cancel(message);
+			process.exit(1);
+		};
 		const requested = args.template;
-		let template;
+		let selected;
 		if (requested) {
-			if (!isTemplate(requested)) {
-				p.cancel(`Unknown template "${requested}". Available: ${TEMPLATES.join(", ")}`);
-				process.exit(1);
-			}
-			template = requested;
-		} else template = orCancel(await p.select({
-			message: "Template",
-			options: TEMPLATES.map((id) => ({
-				value: id,
-				label: id
-			}))
-		}));
-		const name = args.name ? String(args.name).trim() : orCancel(await p.text({
-			message: "Project name",
+			selected = templates.find((entry) => entry.id === requested);
+			if (!selected) return cancelFrom(`Unknown template "${requested}". Available: ${templates.map((entry) => entry.id).join(", ")}`);
+		} else {
+			const id = orCancel(await p.select({
+				message: "Template",
+				options: templates.map((entry) => ({
+					value: entry.id,
+					label: entry.label
+				}))
+			}));
+			selected = templates.find((entry) => entry.id === id);
+		}
+		if (!selected) return cancelFrom("No template selected.");
+		const template = selected.id;
+		const templateDir = selected.dir;
+		const label = selected.label;
+		const fail = cancelFrom;
+		const manifest = readManifest(templateDir);
+		const minErr = minCliError(manifest);
+		if (minErr) return fail(minErr);
+		const name = normalizeProjectName(args.name ? String(args.name) : orCancel(await p.text({
+			message: "What is your project named?",
 			placeholder: "my-app",
 			validate: projectName
-		}));
-		if (!args.name) {
-			const check = projectName(name);
-			if (check) {
-				p.cancel(check);
-				process.exit(1);
-			}
-		}
-		const dir = path.resolve(cwd, name);
-		if (fs.existsSync(dir)) {
-			p.cancel(`${name} already exists — pick a different name or remove it.`);
-			process.exit(1);
-		}
-		const preset = getPreset(template);
-		if (!preset) {
-			p.cancel(`No preset for template "${template}".`);
+		})));
+		const invalid = projectName(name);
+		if (invalid) {
+			p.cancel(invalid);
 			process.exit(1);
 		}
+		const dir = path.resolve(cwd, name);
+		if (fs.existsSync(dir)) return cancelFrom(`${name} already exists — pick a different name or remove it.`);
 		const installed = availablePackageManagers(PACKAGE_MANAGERS);
 		const invokingPm = detectInvokingPackageManager();
 		const defaultPm = invokingPm && installed.includes(invokingPm) ? invokingPm : installed[0];
@@ -163,45 +206,32 @@ const create = defineCommand({
 			})),
 			initialValue: defaultPm
 		}));
-		const conn = await collectConnectionInteractively(preset, { baseUrl: `http://localhost:${await pickAppPort()}` });
-		if (preset.apiPath && conn.baseUrl) conn.baseUrl = withApiPath(conn.baseUrl, preset.apiPath);
+		const conn = await collectConnectionInteractively(manifest.apiPath, { baseUrl: `http://localhost:${await pickAppPort()}` });
+		if (manifest.apiPath && conn.baseUrl) conn.baseUrl = withApiPath(conn.baseUrl, manifest.apiPath);
 		const includeExamples = orCancel(await p.confirm({
 			message: "Add examples?",
 			initialValue: true
 		}));
-		const fetched = await fetchTemplate(template);
-		const fail = (message) => {
-			fetched.cleanup();
-			p.cancel(message);
-			process.exit(1);
-		};
-		const manifest = readManifest(fetched.dir);
-		const minErr = minCliError(manifest);
-		if (minErr) fail(minErr);
 		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);
-		}
+		if (!bootstrap) return fail(`Template "${template}" can't be scaffolded — its manifest declares no framework bootstrap.`);
 		const s = p.spinner();
-		s.start(`Creating ${name} with the ${preset.label} CLI`);
+		s.start(`Creating ${name} with the ${label} CLI`);
 		const scaffold = runCommandCaptured(bootstrap, cwd);
-		s.stop(scaffold.ok ? `Created ${name} with the ${preset.label} CLI` : `${preset.label} setup failed`);
+		s.stop(scaffold.ok ? `Created ${name} with the ${label} CLI` : `${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.`);
+			fail(`${label} setup failed — see the output above and try again.`);
 		}
-		const exampleTemplate = readEnvExample(fetched.dir);
+		const exampleTemplate = readEnvExample(templateDir);
 		try {
-			await applyManifestWiring(dir, fetched.dir, manifest, {
+			await applyManifestWiring(dir, templateDir, manifest, {
 				includeExamples,
 				localDev: conn.mode === "local"
 			});
 		} catch (error) {
 			fail(error instanceof Error ? error.message : String(error));
 		}
-		fetched.cleanup();
+		fetchedRegistry.cleanup();
 		let depsInstalled = false;
 		if (orCancel(await p.confirm({
 			message: "Install dependencies now?",
@@ -214,7 +244,7 @@ const create = defineCommand({
 			if (!depsInstalled) p.log.warn(`Install them yourself: cd ${name} && ${installArgs(pm).join(" ")}`);
 		}
 		await setupLocalWordPress(dir, conn);
-		await writeEnv(dir, resolveEnvKeys(preset, manifest), conn, {
+		await writeEnv(dir, resolveEnvKeys(manifest), conn, {
 			force: true,
 			yes: false,
 			exampleTemplate

package/dist/cli/commands/generate.js

@@ -15,6 +15,10 @@ const generate = defineCommand({
 	} },
 	async run({ args }) {
 		const cfg = await resolveConfig(process.cwd(), { dir: args.dir });
+		if (!cfg) {
+			log.info("No Kizlo server directory configured, nothing to generate. Set `dir` in kizlo.config.ts or pass --dir.");
+			return;
+		}
 		let ok;
 		try {
 			ok = await generateOnce(cfg);

package/dist/cli/commands/init.js

@@ -1,7 +1,6 @@
 import { addDependencyArgs, detectImportAlias, detectPackageManager, ensureGitignored, getVersion, loadEnvFiles, runCommandAsync } from "../utils.js";
-import { PRESETS, detectPreset, getPreset } from "../presets/index.js";
-import { fetchTemplate } from "../presets/source.js";
-import { adaptFile, changesFor, fileEntries, isOlderVersion, minCliError, patchEntries, readManifest, resolveDependencies } from "../presets/template.js";
+import { DEFAULT_REGISTRY, detectTemplates, fetchRegistry, isSingleTemplate, listTemplates, resolveRegistry } from "../presets/source.js";
+import { adaptFile, changesFor, fileEntries, isOlderVersion, minCliError, patchEntries, readManifest, renderNote, resolveDependencies } from "../presets/template.js";
 import { collectConnectionFromEnv, collectConnectionInteractively, dirPath, nextStepsNote, orCancel, readEnvExample, resolveEnvKeys, setupLocalWordPress, syncRemote, validate, withApiPath, writeEnv } from "./_setup.js";
 import { applyLayoutPatches, buildScaffoldContext, kizloConfigTemplate, reportScaffold, scaffoldFile, writeGeneratedContract } from "./_wiring.js";
 import path from "node:path";
@@ -25,7 +24,20 @@ function sameOrigin(a, b) {
 		return false;
 	}
 }
-function detectAppDir(cwd, hasSrcDir) {
+/**
+* The framework's route directory in the user's project. When a template is present its
+* `conventions.appDir` (e.g. `src/app` for Next, `src/pages` for Astro) is the expected layout; we
+* probe that path and its no-`src` variant so a project that keeps routes at the top level is still
+* found, falling back to whether the project has a `src` dir. With no known template appDir we keep the
+* App Router default.
+*/
+function detectAppDir(cwd, hasSrcDir, templateAppDir) {
+	if (templateAppDir) {
+		const withoutSrc = templateAppDir.replace(/^src\//, "");
+		if (fs.existsSync(path.join(cwd, templateAppDir))) return templateAppDir;
+		if (fs.existsSync(path.join(cwd, withoutSrc))) return withoutSrc;
+		return hasSrcDir ? templateAppDir : withoutSrc;
+	}
 	if (fs.existsSync(path.join(cwd, "src", "app"))) return "src/app";
 	if (fs.existsSync(path.join(cwd, "app"))) return "app";
 	return hasSrcDir ? "src/app" : "app";
@@ -37,7 +49,7 @@ async function collectInteractively(ctx) {
 		validate: validate(dirPath)
 	}));
 	let alias = "";
-	if (ctx.preset.apiPath) {
+	if (ctx.apiPath) {
 		const serverDir = path.join(dir.replace(/^\.\//, "").replace(/\/+$/, ""), "server");
 		const detected = detectImportAlias(ctx.cwd, serverDir)?.prefix;
 		alias = orCancel(await p.text({
@@ -47,7 +59,7 @@ async function collectInteractively(ctx) {
 		})).trim();
 	}
 	return {
-		...await collectConnectionInteractively(ctx.preset),
+		...await collectConnectionInteractively(ctx.apiPath),
 		dir,
 		alias
 	};
@@ -63,7 +75,7 @@ function collectFromEnv(ctx) {
 	return {
 		...conn,
 		dir,
-		alias: ctx.preset.apiPath ? aliasWithSlash(detectImportAlias(ctx.cwd, path.join(dir, "server"))?.prefix) : ""
+		alias: ctx.apiPath ? aliasWithSlash(detectImportAlias(ctx.cwd, path.join(dir, "server"))?.prefix) : ""
 	};
 }
 function readPkg(pkgPath) {
@@ -105,13 +117,13 @@ const init = defineCommand({
 			description: "Overwrite existing .env values and server entry without asking",
 			default: false
 		},
-		preset: {
-			type: "string",
-			description: `Force a setup preset (${PRESETS.map((preset) => preset.id).join(", ")})`
-		},
 		alias: {
 			type: "string",
 			description: "Import alias prefix for generated imports (e.g. @); blank for relative"
+		},
+		source: {
+			type: "string",
+			description: "Where to wire from — a local dir or giget source, either a registry of templates or a single template (default: Kizlo's GitHub templates)"
 		}
 	},
 	async run({ args }) {
@@ -136,73 +148,109 @@ const init = defineCommand({
 		const pm = detectPackageManager(cwd);
 		const hasKizlo = Boolean(pkg.dependencies?.kizlo) || Boolean(pkg.devDependencies?.kizlo);
 		const hasSrcDir = fs.existsSync(path.join(cwd, "src"));
-		const initCtx = {
-			cwd,
-			pkg,
-			pm,
-			hasSrcDir
-		};
-		let preset;
-		if (args.preset) {
-			const chosen = getPreset(String(args.preset));
-			if (!chosen) {
-				p.cancel(`Unknown preset "${args.preset}". Available: ${PRESETS.map((pr) => pr.id).join(", ")}`);
-				process.exit(1);
-			}
-			preset = chosen;
-		} else {
-			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);
-		let manifest;
-		let fetched;
-		if (preset.template) {
-			fetched = await fetchTemplate(preset.template);
-			manifest = readManifest(fetched.dir);
-			const minErr = minCliError(manifest);
-			if (minErr) {
-				fetched.cleanup();
-				p.cancel(minErr);
-				process.exit(1);
-			}
+		const registry = resolveRegistry(args.source ? String(args.source) : void 0);
+		let fetchedRegistry;
+		try {
+			fetchedRegistry = await fetchRegistry(registry);
+		} catch (error) {
+			p.cancel(error instanceof Error ? error.message : String(error));
+			process.exit(1);
 		}
-		const envKeys = resolveEnvKeys(preset, manifest);
+		const cancelFrom = (message) => {
+			fetchedRegistry.cleanup();
+			p.cancel(message);
+			process.exit(1);
+		};
 		try {
+			const entries = listTemplates(fetchedRegistry.dir);
+			if (entries.length === 0) cancelFrom(`No templates found in ${registry.source}. Each template needs a template.json.`);
+			const projectDeps = {
+				...pkg.dependencies,
+				...pkg.devDependencies
+			};
+			let entry;
+			if (isSingleTemplate(fetchedRegistry.dir)) {
+				const [only] = entries;
+				entry = only;
+				if (only && detectTemplates(entries, projectDeps).length === 0) {
+					p.log.warn(`The ${only.label} template doesn't match this project's dependencies — detection may be off on either side.`);
+					if (!(yes || orCancel(await p.confirm({
+						message: `Apply ${only.label} anyway?`,
+						initialValue: false
+					})))) cancelFrom("Cancelled. Point --source at a template that matches this project, or omit it to auto-detect.");
+				}
+			} else {
+				const matched = detectTemplates(entries, projectDeps);
+				const [first] = matched;
+				if (matched.length === 0) {
+					p.log.warn(`Couldn't find a template matching this project's framework ${registry.source === DEFAULT_REGISTRY ? "in Kizlo templates" : `at your provided source ${registry.source}`}.`);
+					if (yes) cancelFrom(`Re-run with --source pointing at the single template you want, or run without --yes to pick one manually.`);
+					if (!orCancel(await p.confirm({
+						message: "Pick a template manually anyway?",
+						initialValue: false
+					}))) cancelFrom("Cancelled.");
+					const id = orCancel(await p.select({
+						message: "Choose a template to apply",
+						options: entries.map((e) => ({
+							value: e.id,
+							label: e.label
+						}))
+					}));
+					entry = entries.find((e) => e.id === id);
+				} else if (matched.length === 1 && first) {
+					entry = first;
+					p.log.success(`${first.label} detected`);
+				} else {
+					const ids = matched.map((e) => e.id).join(", ");
+					if (yes) cancelFrom(`Multiple templates match this project (${ids}). Re-run with --source pointing at the single template you want.`);
+					const id = orCancel(await p.select({
+						message: "Multiple templates match this project — pick one",
+						options: matched.map((e) => ({
+							value: e.id,
+							label: e.label
+						}))
+					}));
+					entry = matched.find((e) => e.id === id);
+				}
+			}
+			if (!entry) return cancelFrom("No template selected.");
+			const manifest = readManifest(entry.dir);
+			const minErr = minCliError(manifest);
+			if (minErr) cancelFrom(minErr);
+			if (manifest.requires && !manifest.requires.anyDir.some((rel) => fs.existsSync(path.join(cwd, rel)))) cancelFrom(manifest.requires.message);
+			const apiPath = manifest.apiPath;
+			const envKeys = resolveEnvKeys(manifest);
 			const setup = yes ? collectFromEnv({
 				cwd,
 				hasSrcDir,
-				preset,
+				apiPath,
 				envKeys
 			}) : await collectInteractively({
 				cwd,
 				hasSrcDir,
-				preset
+				apiPath
 			});
 			if (args.alias !== void 0) setup.alias = String(args.alias).trim();
 			setup.alias = aliasWithSlash(setup.alias);
-			const includeExamples = manifest && fetched ? yes ? true : orCancel(await p.confirm({
+			const includeExamples = yes ? true : orCancel(await p.confirm({
 				message: "Add example pages?",
 				initialValue: true
-			})) : false;
+			}));
 			if (!hasKizlo) {
-				const spec = `kizlo@${manifest?.dependencies?.kizlo ?? `^${getVersion()}`}`;
+				const spec = `kizlo@${manifest.dependencies?.kizlo ?? `^${getVersion()}`}`;
 				const s = p.spinner();
 				s.start(`Installing kizlo with ${pm}`);
 				const ok = await runCommandAsync(addDependencyArgs(pm, spec), cwd, "ignore");
 				s.stop(ok ? "Installed kizlo" : "Could not install kizlo automatically");
 				if (!ok) p.log.warn(`Install it yourself: ${addDependencyArgs(pm, spec).join(" ")}`);
 			}
-			if (preset.apiPath && setup.baseUrl) setup.baseUrl = withApiPath(setup.baseUrl, preset.apiPath);
+			if (apiPath && setup.baseUrl) setup.baseUrl = withApiPath(setup.baseUrl, apiPath);
 			await setupLocalWordPress(cwd, setup);
 			await writeEnv(cwd, envKeys, setup, {
 				force,
 				yes,
-				exampleTemplate: fetched ? readEnvExample(fetched.dir) : void 0
+				exampleTemplate: readEnvExample(entry.dir)
 			});
 			await syncRemote(setup);
 			const dirRel = setup.dir.replace(/^\.\//, "").replace(/\/+$/, "");
@@ -210,7 +258,7 @@ const init = defineCommand({
 			const clientUrl = setup.siteUrl && !sameOrigin(setup.siteUrl, setup.baseUrl) ? setup.baseUrl : void 0;
 			const scaffold = buildScaffoldContext(cwd, {
 				dirRel,
-				appDir: detectAppDir(cwd, hasSrcDir),
+				appDir: detectAppDir(cwd, hasSrcDir, manifest.conventions.appDir),
 				alias: setup.alias,
 				clientUrl
 			});
@@ -219,10 +267,8 @@ const init = defineCommand({
 				relPath: "kizlo.config.ts",
 				contents: kizloConfigTemplate(dirRel, setup.alias, setup.mode === "local")
 			}];
-			if (manifest && fetched) {
-				await alignDependencies(cwd, pm, pkg, manifest);
-				for (const entry of fileEntries(changesFor(manifest, "init", { includeExamples }))) files.push(adaptFile(fetched.dir, entry, manifest.conventions, scaffold));
-			} else if (preset.scaffolds) files.push(...preset.scaffolds(scaffold));
+			await alignDependencies(cwd, pm, pkg, manifest);
+			for (const fileEntry of fileEntries(changesFor(manifest, "init", { includeExamples }))) files.push(adaptFile(entry.dir, fileEntry, manifest.conventions, scaffold));
 			const scaffolded = [];
 			for (const file of files) scaffolded.push({
 				file,
@@ -235,12 +281,16 @@ const init = defineCommand({
 			const gitignore = ensureGitignored(cwd, ".env");
 			ensureGitignored(cwd, ".kizlo/");
 			for (const { file, result } of scaffolded) reportScaffold(file, result, yes);
-			if (manifest) applyLayoutPatches(cwd, patchEntries(changesFor(manifest, "init")), manifest.conventions, scaffold);
+			applyLayoutPatches(cwd, patchEntries(changesFor(manifest, "init")), manifest.conventions, scaffold);
+			for (const note of manifest.notes ?? []) {
+				const rendered = renderNote(note, setup.alias);
+				p.note(rendered.body, rendered.title);
+			}
 			if (gitignore !== "present") p.log.success(`${gitignore === "created" ? "Created" : "Updated"} .gitignore (ignoring .env)`);
 			nextStepsNote(setup);
 			p.outro("Kizlo is ready 🎉");
 		} finally {
-			fetched?.cleanup();
+			fetchedRegistry.cleanup();
 		}
 	}
 });

package/dist/cli/daemon/config.js

@@ -2,10 +2,10 @@ import { LOCAL_DIR_REL } from "../wp/constants.js";
 import { credentialsPath, findConfigDir } from "../wp/utils.js";
 import { log } from "./logger.js";
 import { detectPackageManager } from "../utils.js";
+import { importIgnoringVirtualModules } from "./jiti.js";
 import z from "zod/v4";
 import path from "node:path";
 import fs from "node:fs";
-import { createJiti } from "jiti";
 
 //#region src/cli/daemon/config.ts
 const fixtureSchema = z.custom((value) => typeof value === "object" && value !== null && typeof value.name === "string", { message: "must be a fixture object with a string `name` (use defineFixture)" });
@@ -41,15 +41,12 @@ const CONFIG_FILES = [
 const DEFAULT_DEV_PORT = 8080;
 const DEFAULT_DEV_DB_PORT = 3307;
 const DEFAULT_TEST_PORT = 8889;
-function defaultDir(cwd) {
-	return fs.existsSync(path.join(cwd, "src")) ? "src/lib/kizlo" : "lib/kizlo";
-}
 async function loadConfigFile(cwd) {
 	const file = CONFIG_FILES.map((name) => path.join(cwd, name)).find((p) => fs.existsSync(p));
 	if (!file) return void 0;
 	let raw;
 	try {
-		const mod = await createJiti(cwd, { moduleCache: false }).import(file);
+		const mod = await importIgnoringVirtualModules(cwd, file);
 		raw = mod.default ?? mod;
 	} catch (error) {
 		log.error(`Could not load ${path.basename(file)}:`, error);
@@ -62,9 +59,18 @@ async function loadConfigFile(cwd) {
 	}
 	return result.data;
 }
+/**
+* Resolve the Kizlo server layout from an explicit `dir` — the `--dir` flag or `dir` in
+* `kizlo.config.*`. Returns `undefined` when neither is set: there's no Kizlo server to
+* generate a contract from, so callers skip generation and (for `dev`) run local WordPress
+* alone. There's intentionally no default path — a missing `dir` means "no server", not
+* "look under `lib/kizlo`".
+*/
 async function resolveConfig(cwd, flags) {
 	const fileConfig = await loadConfigFile(cwd);
-	const dir = (flags?.dir ?? fileConfig?.dir ?? defaultDir(cwd)).replace(/^\.\//, "").replace(/\/+$/, "");
+	const raw = flags?.dir ?? fileConfig?.dir;
+	if (!raw) return void 0;
+	const dir = raw.replace(/^\.\//, "").replace(/\/+$/, "");
 	const serverDir = path.join(dir, "server");
 	const generatedDir = path.join(serverDir, "generated");
 	return {