kizlo 0.10.0 → 0.12.0

package/README.md

@@ -23,16 +23,16 @@ Kizlo is an open-source framework for building content-driven applications with
 
 ## Quick start
 
-Set up Kizlo in your project:
+Scaffold a new project with Kizlo already wired:
 
 ```bash
-npx kizlo@latest init
+npx kizlo@latest create
 ```
 
-Start the local WordPress stack:
+Or add Kizlo to an existing project:
 
 ```bash
-npx kizlo dev
+npx kizlo@latest init
 ```
 
 See the [docs](https://kizlo.io/docs) for the full guide.

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

@@ -7,6 +7,7 @@ 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 { isPluginVersionSupported, pluginUpdateMessage } from "@kizlo/shared";
 import z from "zod/v4";
 import path from "node:path";
 import fs from "node:fs";
@@ -16,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) {
@@ -80,7 +81,11 @@ function managedEnv(envKeys, conn) {
 	};
 }
 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 urlString = requiredString.pipe(z.url({
+	protocol: /^https?$/,
+	hostname: /^(localhost|(\d{1,3}\.){3}\d{1,3}|([a-zA-Z0-9-]+\.)+[a-zA-Z]{2,})$/,
+	error: "Must be a valid http(s) URL with a real host (e.g. https://example.com)"
+}));
 const dirPath = requiredString.refine((value) => !value.endsWith(".ts"), "Enter a directory, not a file");
 function validate(schema) {
 	return (value) => {
@@ -130,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)
@@ -382,7 +387,11 @@ async function syncRemote(conn) {
 		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.`);
+	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.`);
+		return;
+	}
+	if (!isPluginVersionSupported(sync.pluginVersion)) p.log.warn(pluginUpdateMessage(sync.pluginVersion));
 }
 /** The "Next steps" lines. `kizlo dev` is the single entry point for development. */
 function nextStepsLines(conn, prefix = "") {

package/dist/cli/commands/create.js

@@ -1,7 +1,6 @@
 import { availablePackageManagers, detectInvokingPackageManager, ensureGitignored, frameworkCreateArgs, installArgs, runCommandAsync, runCommandCaptured } from "../utils.js";
-import { getPreset } from "../presets/index.js";
-import { fetchTemplate } from "../presets/source.js";
-import { adaptFile, changesFor, fileEntries, isExample, minCliError, patchEntries, readManifest, resolveDependencies } from "../presets/template.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";
 import z from "zod/v4";
@@ -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}
@@ -63,8 +85,8 @@ function bootstrapArgs(manifest, pm, name) {
 * Layer Kizlo's wiring onto a freshly bootstrapped app in `dir`, from an already-fetched template
 * directory + manifest. The framework CLI has produced the base project (package.json, config,
 * tsconfig, the root layout); this drives the manifest — the same engine `init` uses — to record the
-* `kizlo` dependency, write `kizlo.config.ts`, scaffold the manifest's files (the `base` plumbing and
-* the `create` layout/styles always, the `example`-flagged demo pages only when `includeExamples`),
+* `kizlo` dependency, write `kizlo.config.ts`, scaffold the manifest's files (core wiring from `base`
+* and `create` always, the `example`-flagged demo pages only when `includeExamples`),
 * seed the generated contract, and ignore `.env` and the `.kizlo/` working dir (which holds the local WordPress install). On a fresh app Kizlo owns the layout, so `create`
 * writes it whole (already SEO-wired) rather than patching — `applyLayoutPatches` runs over `create`'s
 * patches, which are none today. The target directory layout comes straight from the manifest's
@@ -80,7 +102,7 @@ async function applyManifestWiring(dir, templateDir, manifest, opts) {
 		clientUrl: void 0
 	});
 	recordDependencies(dir, manifest);
-	const changes = changesFor(manifest, "create").filter((change) => opts.includeExamples || !isExample(change));
+	const changes = changesFor(manifest, "create", { includeExamples: opts.includeExamples });
 	const files = [{
 		label: "Kizlo config",
 		relPath: "kizlo.config.ts",
@@ -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/dev.js

@@ -1,4 +1,6 @@
 import { createStack, dockerHint, dockerStatus } from "../wp/docker.js";
+import { findConfigDir } from "../wp/utils.js";
+import { log } from "../daemon/logger.js";
 import { DEFAULT_ENV_KEYS, ensureGitignored, envGroups, groupDefault, mergeEnv, pickStackPort, withSpinner } from "../utils.js";
 import { resolveDevConfig, usesLocalWordPress } from "../daemon/config.js";
 import { bootstrapDev } from "../wp/dev.js";
@@ -6,6 +8,7 @@ import { reapOrphans, registerSession, removeProjectContainers, spawnWatchdog, u
 import { syncSiteSettings } from "../wp/settings.js";
 import { devStack } from "../wp/stack.js";
 import { palette } from "../banner.js";
+import { watchReload } from "../daemon/reload.js";
 import { startWatcher } from "../daemon/watch.js";
 import { join } from "node:path";
 import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
@@ -166,13 +169,13 @@ function armForegroundTeardown(cfg) {
 	}
 }
 /**
-* Boot local WordPress and run in the foreground until exit — the path behind bare
-* `kizlo dev`. Arms teardown first (so a mid-startup cancel still
-* stops partial containers), shows a timed spinner, prints the summary + stop hint, then
-* parks. A referenced timer holds the event loop open — an unresolved promise alone would
-* not, so without it Node would empty its loop and exit straight after printing.
+* Bring the dev stack's containers up for `cfg`: clear any stale containers, resolve the published
+* ports (stepping off a collision unless the port is pinned in config), write the compose files, and
+* note any port that moved. Returns `cfg` with the resolved ports — the shape the rest of the boot
+* and the teardown work against. Shared by the first boot and every reload reboot, so a changed
+* `dev.port` in `kizlo.config.ts` is re-resolved the same way each time.
 */
-async function startForeground(cfg) {
+async function prepareStack(cfg) {
 	await removeProjectContainers(cfg.project);
 	const port = await pickStackPort(cfg.port, {
 		fixed: cfg.portExplicit,
@@ -191,11 +194,17 @@ async function startForeground(cfg) {
 	createStack(devStack(ready));
 	if (port !== cfg.port) note(`Port ${cfg.port} is in use — serving on ${port} instead.`);
 	if (dbPort !== cfg.dbPort) note(`Database port ${cfg.dbPort} is in use — using ${dbPort} instead.`);
-	armForegroundTeardown(ready);
-	const start = Date.now();
-	const creds = await withSpinner("Starting local WordPress", () => bootstrapDev(ready));
+	return ready;
+}
+/**
+* After a boot, sync the fresh credentials (or the current LAN URL) into `.env` and the plugin, print
+* the connection summary, and print the timed ready line. `reloaded` swaps the wording and drops the
+* one-time Ctrl+C hint. `start` is when the boot began, so the timing spans the whole reboot including
+* the spinner. The `.env` writes here are why the caller pauses the reload watcher around a reboot.
+*/
+async function report(cfg, creds, reloaded, start) {
 	if (creds.appPassword) {
-		const env = updateWpEnv(ready, creds);
+		const env = updateWpEnv(cfg, creds);
 		note("Updated .env with the new WordPress credentials");
 		if (env) {
 			const sync = await syncSiteSettings({
@@ -209,34 +218,118 @@ async function startForeground(cfg) {
 			});
 			if (!sync.ok) note(`Could not sync the site settings to WordPress (${sync.error}) — make sure the kizlo plugin is active, then set them from the Kizlo settings.`);
 		}
-	} else if (syncLocalUrl(ready, creds.url)) note("Updated .env WordPress URL to the current network address — restart your app to pick it up");
+	} else if (syncLocalUrl(cfg, creds.url)) note("Updated .env WordPress URL to the current network address — restart your app to pick it up");
 	printSummary(creds);
 	const { green, dim, bold, reset } = palette();
 	const ms = Date.now() - start;
 	const took = ms < 1e3 ? `${ms}ms` : `${(ms / 1e3).toFixed(1)}s`;
-	process.stdout.write(`\n   ${dim}Press ${reset}${bold}Ctrl+C${reset}${dim} (or close the terminal) to stop local WordPress${reset}\n`);
-	process.stdout.write(`\n ${green}✓${reset} Ready in ${took}\n\n`);
-	const stopWatcher = await startWatcher(ready.configDir);
-	if (stopWatcher) process.on("exit", stopWatcher);
+	if (!reloaded) process.stdout.write(`\n   ${dim}Press ${reset}${bold}Ctrl+C${reset}${dim} (or close the terminal) to stop local WordPress${reset}\n`);
+	process.stdout.write(`\n ${green}✓${reset} ${reloaded ? "Reloaded" : "Ready"} in ${took}\n\n`);
+}
+/**
+* Boot local WordPress for an already-prepared `cfg` (ports resolved, teardown armed) behind a spinner,
+* then report. The first-boot path only — reboots go through {@link rebootStack}, which also folds the
+* prepare step under the spinner.
+*/
+async function bootAndReport(cfg) {
+	const start = Date.now();
+	await report(cfg, await withSpinner("Starting local WordPress", () => bootstrapDev(cfg)), false, start);
+}
+/**
+* Reboot the whole stack in place after a config/env change: re-resolve the config, recreate the
+* containers, and boot WordPress — all behind a single spinner labelled with the file that changed, so
+* there's no loaderless gap between detecting the change and the boot. Teardown is already armed from
+* the first boot, so this never re-arms. Returns the freshly resolved config (ports may have moved) so
+* the caller can re-target its watchers.
+*/
+async function rebootStack(cwd, label) {
+	const start = Date.now();
+	const { ready, creds } = await withSpinner(label, async () => {
+		const ready$1 = await prepareStack(await resolveDevConfig(cwd));
+		return {
+			ready: ready$1,
+			creds: await bootstrapDev(ready$1)
+		};
+	});
+	await report(ready, creds, true, start);
+	return ready;
+}
+/**
+* Boot local WordPress and run in the foreground until exit — the path behind bare `kizlo dev`. Arms
+* teardown first (so a mid-startup cancel still stops partial containers), boots and prints the
+* summary, then parks. While parked it watches `.env` and `kizlo.config.*`: a change reboots the whole
+* stack in place so a new port, connection, or fixture takes effect without rerunning the command. The
+* reboot runs in the same process — the watchdog and session keep watching this PID throughout — and is
+* guarded so the credential/URL writes it makes to `.env` don't trigger another reboot. A referenced
+* timer holds the event loop open — an unresolved promise alone would not, so without it Node would
+* empty its loop and exit straight after printing.
+*/
+async function startForeground(cfg) {
+	const cwd = process.cwd();
+	let ready = await prepareStack(cfg);
+	armForegroundTeardown(ready);
+	await bootAndReport(ready);
+	let stopContract = await startWatcher(ready.configDir);
+	let reloading = false;
+	const reload = async (changed) => {
+		if (reloading) return;
+		reloading = true;
+		try {
+			stopContract?.();
+			ready = await rebootStack(cwd, `${changed} changed — restarting the session`);
+			stopContract = await startWatcher(ready.configDir);
+		} catch (error) {
+			log.error("Failed to reload the dev session:", error);
+		} finally {
+			setTimeout(() => {
+				reloading = false;
+			}, 500);
+		}
+	};
+	const stopReload = watchReload(ready.configDir, (changed) => void reload(changed));
+	process.on("exit", () => {
+		stopContract?.();
+		stopReload();
+	});
 	setInterval(() => {}, 1 << 30);
 	await new Promise(() => {});
 }
 /**
 * Run the contract watcher in the foreground until exit — the path bare `kizlo dev` takes when local
 * WordPress isn't configured (a project pointing at its own WordPress). Generates once, then watches
-* the server files and regenerates on save. Returns immediately when another watcher already holds
-* the lock; otherwise the persistent watcher keeps the process alive on its own.
+* the server files and regenerates on save. It also watches `.env` and `kizlo.config.*` and restarts
+* the watcher on a change, so a new server dir or env value is picked up the same way the local path
+* reboots its stack. Returns immediately when another watcher already holds the lock; otherwise the
+* persistent watcher keeps the process alive on its own.
 */
 async function watchOnly(cwd) {
-	const stop = await startWatcher(cwd);
+	let stop = await startWatcher(cwd);
 	if (!stop) return;
-	process.on("exit", stop);
+	let reloading = false;
+	const reload = async () => {
+		if (reloading) return;
+		reloading = true;
+		try {
+			stop?.();
+			stop = await startWatcher(cwd);
+		} finally {
+			setTimeout(() => {
+				reloading = false;
+			}, 300);
+		}
+	};
+	const stopReload = watchReload(findConfigDir(cwd), () => void reload());
+	const shutdown = () => {
+		stop?.();
+		stopReload();
+	};
+	process.on("exit", shutdown);
 	for (const signal of [
 		"SIGINT",
 		"SIGTERM",
 		"SIGHUP"
 	]) process.on(signal, () => {
-		stop();
+		shutdown();
 		process.exit(0);
 	});
 }

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