kizlo 0.7.0 → 0.8.1

package/dist/category/error.js

@@ -0,0 +1,14 @@
+import { defineErrorMap } from "../shared/error.js";
+
+//#region src/category/error.ts
+const GET_CATEGORY_ERROR_MAP = defineErrorMap({ CATEGORY_NOT_FOUND: {
+	status: 404,
+	message: "Category not found"
+} });
+const LIST_CATEGORY_ERROR_MAP = defineErrorMap({ CATEGORY_INVALID_PAGE: {
+	status: 400,
+	message: "The requested page does not exist."
+} });
+
+//#endregion
+export { GET_CATEGORY_ERROR_MAP, LIST_CATEGORY_ERROR_MAP };

package/dist/category/index.js

@@ -0,0 +1,77 @@
+import { createProcedure } from "../shared/procedure.js";
+import { parseIdentifier } from "../shared/identifier.js";
+import { deserializeListMetadata } from "../shared/serialize.js";
+import { getTaxonomyService } from "../taxonomy/service.js";
+import { GET_CATEGORY_ERROR_MAP, LIST_CATEGORY_ERROR_MAP } from "./error.js";
+import { Category, CategoryList, ListCategoryInput, RetrieveCategoryInput } from "./schema.js";
+import { deserializeCategory } from "./utils.js";
+
+//#region src/category/index.ts
+const CATEGORY_ROUTER_MAP = {
+	get: createProcedure({
+		scope: "api",
+		method: "GET",
+		path: "/categories/{identifier}",
+		params: RetrieveCategoryInput.pick({ identifier: true }),
+		output: Category,
+		errors: GET_CATEGORY_ERROR_MAP
+	}, async ({ input, context, errors }) => {
+		const taxonomy = getTaxonomyService("category", context.wordpress);
+		const identifier = parseIdentifier(input.params.identifier);
+		if (!identifier) throw errors.CATEGORY_NOT_FOUND();
+		const response = await taxonomy.get(identifier);
+		if (response.error) switch (response.error.code) {
+			case "invalid_taxonomy":
+			case "term_not_found":
+			case "rest_term_invalid": throw errors.CATEGORY_NOT_FOUND();
+			default:
+				context.logger.error("Get category unhandled error", response.error, {
+					identifier,
+					code: response.error.code
+				});
+				throw errors.INTERNAL_SERVER_ERROR();
+		}
+		return deserializeCategory(response.data);
+	}),
+	list: createProcedure({
+		scope: "api",
+		method: "GET",
+		path: "/categories",
+		query: ListCategoryInput.optional(),
+		output: CategoryList,
+		errors: LIST_CATEGORY_ERROR_MAP
+	}, async ({ input, context, errors }) => {
+		const response = await getTaxonomyService("category", context.wordpress).list({
+			context: "edit",
+			page: input.query?.page,
+			per_page: input.query?.perPage,
+			search: input.query?.search,
+			exclude: input.query?.exclude,
+			include: input.query?.include,
+			order: input.query?.order,
+			orderby: input.query?.orderBy,
+			hide_empty: input.query?.hideEmpty,
+			parent: input.query?.parent,
+			post: input.query?.post,
+			slug: input.query?.slug
+		});
+		if (response.error) switch (response.error.code) {
+			case "rest_post_invalid_page_number": throw errors.CATEGORY_INVALID_PAGE();
+			default:
+				context.logger.error("List categories unhandled error", response.error, { code: response.error.code });
+				throw errors.INTERNAL_SERVER_ERROR();
+		}
+		const list = context.wordpress.resolveList({
+			data: response.data,
+			headers: response.headers,
+			searchParams: input.query
+		});
+		return {
+			meta: deserializeListMetadata(list.meta),
+			items: list.items.map((item) => deserializeCategory(item))
+		};
+	})
+};
+
+//#endregion
+export { CATEGORY_ROUTER_MAP };

package/dist/category/schema.js

@@ -0,0 +1,40 @@
+import { IdentifierInput, ListMetadata, ListOrder } from "../shared/schema.js";
+import { WP_CATEGORY_ORDER_BYS } from "../wordpress/category/types.js";
+import { Seo } from "../seo/schema.js";
+import { BooleanLike, Metadata, NumberLike, arrayable, lenient } from "@kizlo/shared";
+import z from "zod/v4";
+
+//#region src/category/schema.ts
+const Category = z.object({
+	id: z.number(),
+	name: z.string(),
+	slug: z.string(),
+	url: z.string().nullable(),
+	description: z.string().nullable(),
+	parent: z.number().nullable(),
+	postCount: z.number(),
+	seo: Seo.nullable(),
+	meta: Metadata
+});
+const RetrieveCategoryInput = z.object({ identifier: IdentifierInput });
+const CategoryList = z.object({
+	items: z.array(Category),
+	meta: ListMetadata
+});
+const CategoryOrderBy = z.enum(WP_CATEGORY_ORDER_BYS);
+const ListCategoryInput = z.object({
+	page: NumberLike.pipe(z.number().int().min(1)).catch(1).optional(),
+	perPage: lenient(NumberLike.pipe(z.number().int().min(1).max(100))),
+	search: lenient(z.string()),
+	exclude: lenient(arrayable(NumberLike)),
+	include: lenient(arrayable(NumberLike)),
+	order: lenient(ListOrder),
+	orderBy: lenient(CategoryOrderBy),
+	hideEmpty: lenient(BooleanLike),
+	parent: lenient(NumberLike),
+	post: lenient(NumberLike),
+	slug: lenient(arrayable(z.string()))
+});
+
+//#endregion
+export { Category, CategoryList, ListCategoryInput, RetrieveCategoryInput };

package/dist/category/utils.js

@@ -0,0 +1,20 @@
+import { deserializeSeo } from "../seo/utils.js";
+import { stringifiedMetaRecord } from "@kizlo/shared";
+
+//#region src/category/utils.ts
+function deserializeCategory(data) {
+	return {
+		id: data.id,
+		name: data.name,
+		slug: data.slug,
+		url: data.kizlo.url ?? null,
+		description: data.description.length > 0 ? data.description : null,
+		parent: data.parent > 0 ? data.parent : null,
+		postCount: data.count,
+		seo: data.kizlo.seo ? deserializeSeo(data.kizlo.seo) : null,
+		meta: stringifiedMetaRecord(data.meta ?? {})
+	};
+}
+
+//#endregion
+export { deserializeCategory };

package/dist/cli/banner.js

@@ -7,7 +7,7 @@ const KIZLO_CLI_WORD_MARK = [
 	"██║  ██╗██║███████╗███████╗╚██████╔╝",
 	"╚═╝  ╚═╝╚═╝╚══════╝╚══════╝ ╚═════╝ "
 ];
-const KIZLO_TAGLINE = "Headless WordPress toolkit for TypeScript";
+const KIZLO_TAGLINE = "Headless WordPress framework for TypeScript";
 function colorSupported() {
 	return Boolean(process.stdout.isTTY) && process.env.NO_COLOR === void 0 && process.env.TERM !== "dumb";
 }

package/dist/cli/commands/_setup.js

@@ -0,0 +1,342 @@
+import { composeStop, createStack } from "../wp/docker.js";
+import { ensureGitignored, envGroups, envKeysPresent, mergeEnv, pickStackPort, writeFileIfAbsent } from "../utils.js";
+import { DEFAULT_DEV_DB_PORT, DEFAULT_DEV_PORT, resolveStackName } from "../daemon/config.js";
+import { createAdminAppPassword } from "../wp/bootstrap.js";
+import { bootstrapDev } from "../wp/dev.js";
+import { removeProjectContainers } from "../wp/session.js";
+import { syncSiteSettings } from "../wp/settings.js";
+import { devStack } from "../wp/stack.js";
+import z from "zod/v4";
+import path from "node:path";
+import fs from "node:fs";
+import * as p from "@clack/prompts";
+import { randomBytes } from "node:crypto";
+
+//#region src/cli/commands/_setup.ts
+/** Production connection keys — what a real deploy needs, and what `.env.example` always lists. */
+const PROD_WP_ENV_KEYS = [
+	"KIZLO_SITE_SECRET",
+	"KIZLO_WORDPRESS_URL",
+	"KIZLO_WORDPRESS_USERNAME",
+	"KIZLO_WORDPRESS_APPLICATION_PASSWORD"
+];
+/**
+* The `.env` keys setup manages and the values to write, branched on the connection mode. A local
+* dev stack writes the `KIZLO_DEV_WORDPRESS_*` / `KIZLO_DEV_SITE_SECRET` set plus `KIZLO_TARGET=dev`, so it
+* never touches the production keys (a user can point those at a real site). A remote site writes the
+* bare production keys exactly as before — no `KIZLO_TARGET`, since `"production"` is the default target.
+*/
+function managedEnv(preset, conn) {
+	if (conn.mode === "local") return {
+		keys: [
+			preset.baseUrlEnvKey,
+			"KIZLO_TARGET",
+			"KIZLO_DEV_SITE_SECRET",
+			"KIZLO_DEV_WORDPRESS_URL",
+			"KIZLO_DEV_WORDPRESS_USERNAME",
+			"KIZLO_DEV_WORDPRESS_APPLICATION_PASSWORD"
+		],
+		values: {
+			[preset.baseUrlEnvKey]: conn.baseUrl,
+			KIZLO_TARGET: "dev",
+			KIZLO_DEV_SITE_SECRET: conn.siteSecret,
+			KIZLO_DEV_WORDPRESS_URL: conn.wpUrl,
+			KIZLO_DEV_WORDPRESS_USERNAME: conn.wpUsername,
+			KIZLO_DEV_WORDPRESS_APPLICATION_PASSWORD: conn.wpPassword
+		}
+	};
+	return {
+		keys: [preset.baseUrlEnvKey, ...PROD_WP_ENV_KEYS],
+		values: {
+			[preset.baseUrlEnvKey]: conn.baseUrl,
+			KIZLO_SITE_SECRET: conn.siteSecret,
+			KIZLO_WORDPRESS_URL: conn.wpUrl,
+			KIZLO_WORDPRESS_USERNAME: conn.wpUsername,
+			KIZLO_WORDPRESS_APPLICATION_PASSWORD: conn.wpPassword
+		}
+	};
+}
+const requiredString = z.string().trim().min(1, "Required");
+const urlString = requiredString.pipe(z.url("Must be a valid URL (e.g. https://example.com)"));
+const dirPath = requiredString.refine((value) => !value.endsWith(".ts"), "Enter a directory, not a file");
+function validate(schema) {
+	return (value) => {
+		const result = schema.safeParse(value ?? "");
+		return result.success ? void 0 : result.error.issues[0]?.message;
+	};
+}
+function orCancel(value) {
+	if (p.isCancel(value)) {
+		p.cancel("Setup cancelled.");
+		process.exit(0);
+	}
+	return value;
+}
+/** Appends the API path to the base URL so the client and route handler agree. */
+function withApiPath(baseUrl, apiPath) {
+	try {
+		const url = new URL(baseUrl);
+		const current = url.pathname.replace(/\/+$/, "");
+		if (current.endsWith(apiPath)) return url.toString().replace(/\/+$/, "");
+		url.pathname = `${current}${apiPath}`;
+		return url.toString().replace(/\/+$/, "");
+	} catch {
+		return baseUrl;
+	}
+}
+/**
+* Collect the WordPress connection interactively: the backend/site URLs, the webhook signing
+* secret, and either the local-dev folder or a remote site's credentials. The caller layers any
+* framework-specific prompts (directory, import alias) on top of what this returns.
+*/
+async function collectConnectionInteractively(preset) {
+	let siteUrl;
+	let baseUrl;
+	if (preset.apiPath) baseUrl = orCancel(await p.text({
+		message: "Public app URL",
+		placeholder: "https://your-app.com",
+		validate: validate(urlString)
+	}));
+	else {
+		siteUrl = orCancel(await p.text({
+			message: "Public site URL",
+			placeholder: "https://your-app.com",
+			validate: validate(urlString)
+		}));
+		baseUrl = orCancel(await p.text({
+			message: "Kizlo backend URL (where the handler is mounted)",
+			placeholder: "https://your-app.com/kizlo",
+			validate: validate(urlString)
+		}));
+	}
+	const siteSecret = orCancel(await p.select({
+		message: "Site secret (webhook signing key)",
+		initialValue: "generate",
+		options: [{
+			value: "generate",
+			label: "Generate a secure secret automatically",
+			hint: "recommended"
+		}, {
+			value: "enter",
+			label: "Enter my own"
+		}]
+	})) === "enter" ? orCancel(await p.password({
+		message: "Enter the site secret",
+		validate: validate(requiredString)
+	})) : randomBytes(32).toString("hex");
+	const mode = orCancel(await p.select({
+		message: "WordPress connection",
+		initialValue: "local",
+		options: [{
+			value: "local",
+			label: "Set up a local dev environment",
+			hint: "runs WordPress in Docker"
+		}, {
+			value: "remote",
+			label: "Use my own WordPress",
+			hint: "connect to an existing site"
+		}]
+	}));
+	let wpUrl = "";
+	let wpUsername = "";
+	let wpPassword = "";
+	let devPath;
+	if (mode === "remote") {
+		wpUrl = orCancel(await p.text({
+			message: "WordPress URL",
+			placeholder: "https://wp.your-app.com",
+			validate: validate(urlString)
+		}));
+		wpUsername = orCancel(await p.text({
+			message: "WordPress username",
+			validate: validate(requiredString)
+		}));
+		wpPassword = orCancel(await p.password({
+			message: "WordPress application password",
+			validate: validate(requiredString)
+		}));
+	} else devPath = orCancel(await p.text({
+		message: "Local WordPress folder",
+		initialValue: "wordpress",
+		validate: validate(dirPath)
+	}));
+	return {
+		mode,
+		baseUrl,
+		siteUrl,
+		siteSecret,
+		wpUrl,
+		wpUsername,
+		wpPassword,
+		devPath
+	};
+}
+/**
+* Non-interactive connection: skip prompts and use env values where present. Missing ones are
+* left empty for the user to fill in later. Never fails — always yields a fillable project.
+*/
+function collectConnectionFromEnv(preset) {
+	return {
+		mode: "remote",
+		baseUrl: process.env[preset.baseUrlEnvKey]?.trim() ?? "",
+		siteSecret: process.env.KIZLO_SITE_SECRET?.trim() || randomBytes(32).toString("hex"),
+		wpUrl: process.env.KIZLO_WORDPRESS_URL?.trim() ?? "",
+		wpUsername: process.env.KIZLO_WORDPRESS_USERNAME?.trim() ?? "",
+		wpPassword: process.env.KIZLO_WORDPRESS_APPLICATION_PASSWORD?.trim() ?? ""
+	};
+}
+/** Build a {@link ResolvedDevConfig} from the chosen install folder, matching `resolveDevConfig`'s
+* defaults — built directly so setup never has to round-trip through the config file it's writing. */
+function devConfigFor(cwd, devPath) {
+	return {
+		configDir: cwd,
+		project: `${resolveStackName(cwd)}-dev`,
+		port: DEFAULT_DEV_PORT,
+		portExplicit: false,
+		dbPort: DEFAULT_DEV_DB_PORT,
+		dbPortExplicit: false,
+		fixtures: [],
+		wordpressPath: devPath,
+		wordpressDir: path.resolve(cwd, devPath)
+	};
+}
+/**
+* Boot the local dev stack once to produce working credentials, then stop it (volumes
+* persist, so a later `kizlo dev` resumes instantly). The dev stack mints no application
+* password — that's a test-stack concern — so we create one here for REST auth in `.env`.
+* While the stack is still up, push the dev site settings (`siteSecret` plus the Kizlo server's
+* `url`/`backend_url`, derived from `baseUrl`) into the plugin so webhook signing and event delivery
+* work.
+*/
+async function provisionLocalStack(cfg, siteSecret, baseUrl) {
+	await removeProjectContainers(cfg.project);
+	const port = await pickStackPort(cfg.port, {
+		fixed: cfg.portExplicit,
+		configKey: "dev.port"
+	});
+	const dbPort = await pickStackPort(cfg.dbPort, {
+		fixed: cfg.dbPortExplicit,
+		host: "127.0.0.1",
+		configKey: "dev.dbPort"
+	});
+	const ready = {
+		...cfg,
+		port,
+		dbPort
+	};
+	createStack(devStack(ready));
+	const info = await bootstrapDev(ready);
+	const appPassword = info.appPassword ?? await createAdminAppPassword("kizlo");
+	const sync = await syncSiteSettings({
+		url: info.url,
+		username: info.username,
+		password: appPassword
+	}, {
+		secret: siteSecret,
+		backendUrl: baseUrl,
+		containerized: true
+	});
+	await composeStop();
+	return {
+		url: info.url,
+		username: info.username,
+		appPassword,
+		adminPassword: info.secrets?.password,
+		secretSyncError: sync.ok ? void 0 : sync.error
+	};
+}
+/**
+* Provision the local WordPress dev stack and fill the connection's WP credentials from it, then
+* report the outcome. Mutates `conn` in place (wpUrl / wpUsername / wpPassword). Exits on failure,
+* matching the previous inline behavior. No-op for a remote connection.
+*/
+async function setupLocalWordPress(cwd, conn) {
+	if (conn.mode !== "local" || !conn.devPath) return;
+	ensureGitignored(cwd, conn.devPath);
+	const s = p.spinner();
+	s.start("Setting up local WordPress (first run downloads images, this can take a while)");
+	try {
+		const local = await provisionLocalStack(devConfigFor(cwd, conn.devPath), conn.siteSecret, conn.baseUrl);
+		conn.wpUrl = local.url;
+		conn.wpUsername = local.username;
+		conn.wpPassword = local.appPassword;
+		s.stop("Local WordPress ready");
+		if (local.secretSyncError) p.log.warn(`Could not sync KIZLO_DEV_SITE_SECRET to the local plugin (${local.secretSyncError})`);
+		p.log.success(`Local WordPress configured (${conn.devPath}) — .env points at ${conn.wpUrl}`);
+		if (local.adminPassword) p.log.warn(`wp-admin login: ${conn.wpUsername} / ${local.adminPassword} — save it, it's shown only once`);
+	} catch (error) {
+		s.stop("Local WordPress setup failed");
+		p.cancel(error instanceof Error ? error.message : String(error));
+		process.exit(1);
+	}
+}
+/**
+* Write (or update) `.env` and `.env.example` for the managed keys and report the outcome.
+* Existing conflicting `.env` values are preserved unless `force`; interactively the user is asked,
+* and under `--yes` they are kept. `.env.example` is only written when absent.
+*/
+async function writeEnv(cwd, preset, conn, opts) {
+	const { keys, values: envValues } = managedEnv(preset, conn);
+	const envPath = path.join(cwd, ".env");
+	const envExisted = fs.existsSync(envPath);
+	const existingEnv = envExisted ? fs.readFileSync(envPath, "utf8") : "";
+	const conflicts = envKeysPresent(existingEnv, keys);
+	let overwriteKeys = new Set(keys);
+	if (conflicts.length && !opts.force) if (opts.yes) {
+		overwriteKeys = /* @__PURE__ */ new Set();
+		p.log.info("Keeping existing .env values (pass --force to overwrite)");
+	} else {
+		p.log.warn("Some environment variables already exist in .env");
+		if (!orCancel(await p.confirm({
+			message: "Overwrite their existing values?",
+			initialValue: true
+		}))) overwriteKeys = /* @__PURE__ */ new Set();
+	}
+	const merge = mergeEnv(existingEnv, envValues, overwriteKeys, envGroups(preset.baseUrlEnvKey));
+	fs.writeFileSync(envPath, merge.content);
+	const exampleKeys = [preset.baseUrlEnvKey, ...PROD_WP_ENV_KEYS];
+	const { content: exampleEnv } = mergeEnv("", Object.fromEntries(exampleKeys.map((key) => [key, ""])), new Set(exampleKeys), envGroups(preset.baseUrlEnvKey));
+	const exampleBody = `${exampleEnv}\n# Point the app at a local dev stack (managed by \`kizlo dev\`) instead of the keys above:\n# KIZLO_TARGET=dev\n`;
+	const exampleCreated = writeFileIfAbsent(path.join(cwd, ".env.example"), exampleBody);
+	if (!envExisted) p.log.success("Created .env");
+	else if (merge.updated.length || merge.added.length) p.log.success("Updated .env");
+	else p.log.info("Left .env unchanged");
+	p.log.success(exampleCreated ? "Created .env.example" : "Skipped .env.example (exists)");
+}
+/**
+* Push the site settings (secret, canonical site URL, backend URL) to a remote WordPress so
+* webhook signing and event delivery work. No-op for local (handled during provisioning) or when
+* credentials are incomplete. Warns and continues on failure.
+*/
+async function syncRemote(conn) {
+	if (conn.mode !== "remote" || !conn.wpUrl || !conn.wpUsername || !conn.wpPassword) return;
+	const sync = await syncSiteSettings({
+		url: conn.wpUrl,
+		username: conn.wpUsername,
+		password: conn.wpPassword
+	}, {
+		secret: conn.siteSecret,
+		siteUrl: conn.siteUrl,
+		backendUrl: conn.baseUrl
+	});
+	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([
+		...mode === "local" ? [
+			`Start your local WordPress dev stack (also watches your extensions):`,
+			`  ${prefix}npx kizlo dev`,
+			``
+		] : [
+			`Watch your extensions and regenerate the contract during development:`,
+			`  ${prefix}npx kizlo watch`,
+			``
+		],
+		`Generate the contract once for production builds:`,
+		`  ${prefix}npx kizlo generate`
+	].join("\n"), "Next steps");
+}
+
+//#endregion
+export { collectConnectionFromEnv, collectConnectionInteractively, dirPath, nextStepsNote, orCancel, setupLocalWordPress, syncRemote, validate, withApiPath, writeEnv };

package/dist/cli/commands/create.js

@@ -0,0 +1,152 @@
+import { dockerAvailable } from "../wp/docker.js";
+import { detectPackageManager, getVersion } 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 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.
+*/
+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)"));
+/**
+* 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.
+*/
+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 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`);
+}
+const create = defineCommand({
+	meta: {
+		name: "create",
+		description: "Scaffold a new project with Kizlo already wired"
+	},
+	args: {
+		template: {
+			type: "positional",
+			required: false,
+			description: `Template to scaffold from (${TEMPLATES.join(", ")})`
+		},
+		name: {
+			type: "positional",
+			required: false,
+			description: "Project folder to create"
+		}
+	},
+	async run({ args }) {
+		const cwd = process.cwd();
+		printBanner(getVersion());
+		p.intro("kizlo create");
+		const requested = args.template;
+		let template;
+		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",
+			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}".`);
+			process.exit(1);
+		}
+		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 s = p.spinner();
+		s.start(`Creating ${name} from the ${template} template`);
+		try {
+			await scaffoldTemplate(template, dir, name);
+			s.stop(`Created ${name}`);
+		} catch (error) {
+			s.stop("Could not create the project");
+			p.cancel(error instanceof Error ? error.message : String(error));
+			process.exit(1);
+		}
+		await setupLocalWordPress(dir, conn);
+		await writeEnv(dir, preset, conn, {
+			force: true,
+			yes: false
+		});
+		await syncRemote(conn);
+		const pm = detectPackageManager(dir);
+		p.note([`cd ${name}`, `${pm} install`].join("\n"), "Get started");
+		nextStepsNote(conn.mode);
+		p.outro("Kizlo is ready 🎉");
+	}
+});
+
+//#endregion
+export { create };

package/dist/cli/commands/dev.js

@@ -2,11 +2,11 @@ import { createStack } from "../wp/docker.js";
 import { ensureGitignored, envGroups, getVersion, groupDefault, mergeEnv, pickStackPort, withSpinner } from "../utils.js";
 import { palette, printBanner } from "../banner.js";
 import { resolveDevConfig } from "../daemon/config.js";
-import { startWatcher } from "../daemon/watch.js";
 import { bootstrapDev } from "../wp/dev.js";
 import { reapOrphans, registerSession, removeProjectContainers, spawnWatchdog, unregisterSession } from "../wp/session.js";
 import { syncSiteSettings } from "../wp/settings.js";
 import { devStack } from "../wp/stack.js";
+import { startWatcher } from "../daemon/watch.js";
 import { join } from "node:path";
 import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { defineCommand } from "citty";