kizlo 0.6.1 → 0.8.0

package/dist/brand/icons.d.ts

@@ -7,29 +7,27 @@ interface IconDescriptor {
   type: string;
   /** `"any"` for scalable/single sources; omitted for `.ico`. */
   sizes?: string;
-  /** Media query for scheme-specific variants, e.g. `(prefers-color-scheme: dark)`. */
-  media?: string;
 }
 interface ManifestIcon {
   src: string;
   type: string;
   sizes: string;
-  /**
-   * `"maskable"` marks art with a safe zone the launcher may crop to any
-   * adaptive shape; omitted (default `"any"`) sources render uncropped.
-   */
-  purpose?: "any" | "maskable";
 }
 interface ResolvedIcons {
-  /** `rel="icon"` candidates: the light source plus an optional dark variant. */
+  /**
+   * `rel="icon"` candidate: a single scheme-agnostic source, or empty. Browsers
+   * disagree on scheme-swapping favicons (Safari ignores the `media` attribute
+   * and never re-evaluates an SVG's internal `@media`), so one icon that reads
+   * on both light and dark tab bars is the only cross-browser-safe surface.
+   */
   icon: IconDescriptor[];
   /** `rel="apple-touch-icon"` candidate (raster-guarded), or empty. */
   appleTouch: IconDescriptor[];
   /**
-   * Web-manifest icon entries (raster or SVG): the square brand icon as the
-   * default `"any"` source — expanded to one entry per real square rendition —
-   * plus the dedicated Android icon as `"maskable"` when provided. Either may
-   * be absent.
+   * Web-manifest icon entries (raster or SVG): a single square source —
+   * expanded to one entry per real square rendition — that every non-iOS
+   * install surface (Android, Chrome, macOS Safari) renders uncropped. Absent
+   * when no manifest-compatible source exists.
    */
   manifestIcons: ManifestIcon[];
 }

package/dist/brand/icons.js

@@ -32,12 +32,20 @@ function manifestSource(media) {
 function pixelSize(media) {
 	return media.width && media.height ? `${media.width}x${media.height}` : "any";
 }
-function toDescriptor(media, extra) {
+/**
+* Append the attachment id as a `?v=` cache-buster. Safari (and every browser)
+* keys its favicon cache by URL, so tying the version to the attachment id means
+* the URL changes when a different icon is chosen — busting the stale cache —
+* while staying stable across renders when the icon is unchanged.
+*/
+function versioned(src, id) {
+	return `${src}${src.includes("?") ? "&" : "?"}v=${id}`;
+}
+function toDescriptor(media) {
 	return {
-		url: media.src,
+		url: versioned(media.src, media.id),
 		type: media.mime ?? "",
-		sizes: media.mime && ICO_MIMES.has(media.mime) ? void 0 : pixelSize(media),
-		...extra
+		sizes: media.mime && ICO_MIMES.has(media.mime) ? void 0 : pixelSize(media)
 	};
 }
 /**
@@ -47,14 +55,12 @@ function toDescriptor(media, extra) {
 * or above the floor so browsers get genuine 192/512-ish icons; if none qualify
 * (e.g. a non-square upload) the original is used as-is.
 */
-function toManifestIcons(media, purpose) {
+function toManifestIcons(media) {
 	const type = media.mime ?? "";
-	const withPurpose = purpose ? { purpose } : {};
 	if (media.mime === SVG_MIME) return [{
 		src: media.src,
 		type,
-		sizes: "any",
-		...withPurpose
+		sizes: "any"
 	}];
 	const square = [{
 		src: media.src,
@@ -75,8 +81,7 @@ function toManifestIcons(media, purpose) {
 		icons.push({
 			src: r.src,
 			type,
-			sizes,
-			...withPurpose
+			sizes
 		});
 	}
 	return icons;
@@ -87,16 +92,13 @@ function toManifestIcons(media, purpose) {
 */
 function resolveIcons(brand) {
 	const icon = [];
-	const light = brand.favicon ?? brand.logo_icon;
-	if (light) icon.push(toDescriptor(light));
-	if (brand.favicon_dark) icon.push(toDescriptor(brand.favicon_dark, { media: "(prefers-color-scheme: dark)" }));
-	const apple = raster(brand.ios_app_icon) ?? raster(brand.favicon);
+	const primary = brand.favicon ?? brand.logo_icon;
+	if (primary) icon.push(toDescriptor(primary));
+	const apple = raster(brand.app_icon) ?? raster(brand.favicon);
 	const appleTouch = apple ? [toDescriptor(apple)] : [];
 	const manifestIcons = [];
-	const anySource = manifestSource(brand.logo_icon) ?? manifestSource(brand.favicon);
+	const anySource = manifestSource(brand.app_icon) ?? manifestSource(brand.logo_icon) ?? manifestSource(brand.favicon);
 	if (anySource) manifestIcons.push(...toManifestIcons(anySource));
-	const maskable = manifestSource(brand.android_app_icon);
-	if (maskable) manifestIcons.push(...toManifestIcons(maskable, "maskable"));
 	return {
 		icon,
 		appleTouch,

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 };