kizlo 0.1.1 → 0.2.1

package/dist/cli/commands/init.js

@@ -1,6 +1,13 @@
-import { addDependencyArgs, detectImportAlias, detectPackageManager, ensureGitignored, envKeysPresent, getVersion, loadEnvFiles, mergeEnv, resolveModuleImport, runCommand, writeFileIfAbsent } from "../utils.js";
-import { CONTRACT_BARREL } from "../daemon/generate.js";
+import { composeStop, createStack, dockerAvailable } from "../wp/docker.js";
+import { addDependencyArgs, detectImportAlias, detectPackageManager, ensureGitignored, envGroups, envKeysPresent, getVersion, loadEnvFiles, mergeEnv, pickStackPort, resolveModuleImport, runCommand, writeFileIfAbsent } from "../utils.js";
 import { printBanner } from "../banner.js";
+import { DEFAULT_DEV_DB_PORT, DEFAULT_DEV_PORT, resolveStackName } from "../daemon/config.js";
+import { CONTRACT_BARREL } from "../daemon/generate.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 { PRESETS, detectPreset, getPreset } from "../presets/index.js";
 import z from "zod/v4";
 import { randomBytes } from "node:crypto";
@@ -10,14 +17,48 @@ import { defineCommand } from "citty";
 import * as p from "@clack/prompts";
 
 //#region src/cli/commands/init.ts
-const WP_ENV_KEYS = [
-	"SITE_SECRET",
-	"WORDPRESS_URL",
-	"WORDPRESS_USERNAME",
-	"WORDPRESS_APPLICATION_PASSWORD"
+/** 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"
 ];
-function envKeys(preset) {
-	return [preset.baseUrlEnvKey, ...WP_ENV_KEYS];
+/**
+* The `.env` keys init 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, setup) {
+	if (setup.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]: setup.baseUrl,
+			KIZLO_TARGET: "dev",
+			KIZLO_DEV_SITE_SECRET: setup.siteSecret,
+			KIZLO_DEV_WORDPRESS_URL: setup.wpUrl,
+			KIZLO_DEV_WORDPRESS_USERNAME: setup.wpUsername,
+			KIZLO_DEV_WORDPRESS_APPLICATION_PASSWORD: setup.wpPassword
+		}
+	};
+	return {
+		keys: [preset.baseUrlEnvKey, ...PROD_WP_ENV_KEYS],
+		values: {
+			[preset.baseUrlEnvKey]: setup.baseUrl,
+			KIZLO_SITE_SECRET: setup.siteSecret,
+			KIZLO_WORDPRESS_URL: setup.wpUrl,
+			KIZLO_WORDPRESS_USERNAME: setup.wpUsername,
+			KIZLO_WORDPRESS_APPLICATION_PASSWORD: setup.wpPassword
+		}
+	};
 }
 function defaultDir(hasSrcDir) {
 	return hasSrcDir ? "src/lib/kizlo" : "lib/kizlo";
@@ -26,11 +67,11 @@ function defaultDir(hasSrcDir) {
 function aliasWithSlash(alias) {
 	return alias ? `${alias.replace(/\/+$/, "")}/` : "";
 }
-function kizloConfigTemplate(dir, alias) {
+function kizloConfigTemplate(dir, alias, devPath) {
 	return `import { defineConfig } from "kizlo/config"
 
 export default defineConfig({
-	dir: "${dir}",${alias ? `\n\talias: "${alias}",` : ""}
+	dir: "${dir}",${alias ? `\n\talias: "${alias}",` : ""}${devPath ? `\n\tdev: { path: "${devPath}" },` : ""}
 })
 `;
 }
@@ -46,6 +87,14 @@ function withApiPath(baseUrl, apiPath) {
 		return baseUrl;
 	}
 }
+/** Whether two URLs share an origin (scheme + host + port); false when either can't be parsed. */
+function sameOrigin(a, b) {
+	try {
+		return new URL(a).origin === new URL(b).origin;
+	} catch {
+		return false;
+	}
+}
 function detectAppDir(cwd, hasSrcDir) {
 	if (fs.existsSync(path.join(cwd, "src", "app"))) return "src/app";
 	if (fs.existsSync(path.join(cwd, "app"))) return "app";
@@ -68,13 +117,27 @@ function orCancel(value) {
 	return value;
 }
 async function collectInteractively(ctx) {
-	const baseUrl = orCancel(await p.text({
-		message: "Public server base URL",
+	let siteUrl;
+	let baseUrl;
+	if (ctx.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 (signing key)",
+		message: "Site secret (webhook signing key)",
 		initialValue: "generate",
 		options: [{
 			value: "generate",
@@ -85,21 +148,44 @@ async function collectInteractively(ctx) {
 			label: "Enter my own"
 		}]
 	})) === "enter" ? orCancel(await p.password({
-		message: "Enter SITE_SECRET",
+		message: "Enter the site secret",
 		validate: validate(requiredString)
 	})) : randomBytes(32).toString("hex");
-	const wpUrl = orCancel(await p.text({
-		message: "WordPress URL",
-		placeholder: "https://wp.your-app.com",
-		validate: validate(urlString)
-	}));
-	const wpUsername = orCancel(await p.text({
-		message: "WordPress username",
-		validate: validate(requiredString)
+	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"
+		}]
 	}));
-	const wpPassword = orCancel(await p.password({
-		message: "WordPress application password",
-		validate: validate(requiredString)
+	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)
 	}));
 	const dir = orCancel(await p.text({
 		message: "Kizlo directory",
@@ -117,11 +203,14 @@ async function collectInteractively(ctx) {
 		})).trim();
 	}
 	return {
+		mode,
 		baseUrl,
+		siteUrl,
 		siteSecret,
 		wpUrl,
 		wpUsername,
 		wpPassword,
+		devPath,
 		dir,
 		alias
 	};
@@ -134,11 +223,12 @@ async function collectInteractively(ctx) {
 function collectFromEnv(ctx) {
 	const dir = defaultDir(ctx.hasSrcDir);
 	return {
+		mode: "remote",
 		baseUrl: process.env[ctx.preset.baseUrlEnvKey]?.trim() ?? "",
-		siteSecret: process.env.SITE_SECRET?.trim() || randomBytes(32).toString("hex"),
-		wpUrl: process.env.WORDPRESS_URL?.trim() ?? "",
-		wpUsername: process.env.WORDPRESS_USERNAME?.trim() ?? "",
-		wpPassword: process.env.WORDPRESS_APPLICATION_PASSWORD?.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() ?? "",
 		dir,
 		alias: ctx.preset.routeHandler ? aliasWithSlash(detectImportAlias(ctx.cwd, path.join(dir, "server"))?.prefix) : ""
 	};
@@ -146,6 +236,66 @@ function collectFromEnv(ctx) {
 function readPkg(pkgPath) {
 	return JSON.parse(fs.readFileSync(pkgPath, "utf8"));
 }
+/** Build a {@link ResolvedDevConfig} from the chosen install folder, matching `resolveDevConfig`'s
+* defaults — built directly so init 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
+	};
+}
 const init = defineCommand({
 	meta: {
 		name: "init",
@@ -218,22 +368,38 @@ const init = defineCommand({
 		});
 		if (args.alias !== void 0) setup.alias = String(args.alias).trim();
 		setup.alias = aliasWithSlash(setup.alias);
+		if (setup.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);
+		}
 		if (!hasKizlo) {
 			const s = p.spinner();
 			s.start(`Installing kizlo with ${pm}`);
-			const ok = runCommand(addDependencyArgs(pm, "kizlo"), cwd, "ignore");
+			const ok = runCommand(addDependencyArgs(pm, "kizlo@latest"), cwd, "ignore");
 			s.stop(ok ? "Installed kizlo" : "Could not install kizlo automatically");
-			if (!ok) p.log.warn(`Install it yourself: ${addDependencyArgs(pm, "kizlo").join(" ")}`);
+			if (!ok) p.log.warn(`Install it yourself: ${addDependencyArgs(pm, "kizlo@latest").join(" ")}`);
 		}
 		if (preset.apiPath && setup.baseUrl) setup.baseUrl = withApiPath(setup.baseUrl, preset.apiPath);
-		const keys = envKeys(preset);
-		const envValues = {
-			[preset.baseUrlEnvKey]: setup.baseUrl,
-			SITE_SECRET: setup.siteSecret,
-			WORDPRESS_URL: setup.wpUrl,
-			WORDPRESS_USERNAME: setup.wpUsername,
-			WORDPRESS_APPLICATION_PASSWORD: setup.wpPassword
-		};
+		let adminPassword;
+		if (setup.mode === "local" && setup.devPath) {
+			ensureGitignored(cwd, setup.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, setup.devPath), setup.siteSecret, setup.baseUrl);
+				setup.wpUrl = local.url;
+				setup.wpUsername = local.username;
+				setup.wpPassword = local.appPassword;
+				adminPassword = local.adminPassword;
+				s.stop("Local WordPress ready");
+				if (local.secretSyncError) p.log.warn(`Could not sync KIZLO_DEV_SITE_SECRET to the local plugin (${local.secretSyncError})`);
+			} catch (error) {
+				s.stop("Local WordPress setup failed");
+				p.cancel(error instanceof Error ? error.message : String(error));
+				process.exit(1);
+			}
+		}
+		const { keys, values: envValues } = managedEnv(preset, setup);
 		const envPath = path.join(cwd, ".env");
 		const envExisted = fs.existsSync(envPath);
 		const existingEnv = envExisted ? fs.readFileSync(envPath, "utf8") : "";
@@ -249,11 +415,26 @@ const init = defineCommand({
 				initialValue: true
 			}))) overwriteKeys = /* @__PURE__ */ new Set();
 		}
-		const merge = mergeEnv(existingEnv, envValues, overwriteKeys);
+		const merge = mergeEnv(existingEnv, envValues, overwriteKeys, envGroups(preset.baseUrlEnvKey));
 		fs.writeFileSync(envPath, merge.content);
-		const exampleCreated = writeFileIfAbsent(path.join(cwd, ".env.example"), `${keys.map((key) => `${key}=`).join("\n")}\n`);
+		if (setup.mode === "remote" && setup.wpUrl && setup.wpUsername && setup.wpPassword) {
+			const sync = await syncSiteSettings({
+				url: setup.wpUrl,
+				username: setup.wpUsername,
+				password: setup.wpPassword
+			}, {
+				secret: setup.siteSecret,
+				siteUrl: setup.siteUrl,
+				backendUrl: setup.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.`);
+		}
+		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);
 		const dirRel = setup.dir.replace(/^\.\//, "").replace(/\/+$/, "");
-		const configCreated = writeFileIfAbsent(path.join(cwd, "kizlo.config.ts"), kizloConfigTemplate(dirRel, setup.alias));
+		const configCreated = writeFileIfAbsent(path.join(cwd, "kizlo.config.ts"), kizloConfigTemplate(dirRel, setup.alias, setup.devPath));
 		const serverDirRel = path.join(dirRel, "server");
 		const serverEntryRel = path.join(serverDirRel, "index.ts");
 		const serverPath = path.join(cwd, serverEntryRel);
@@ -273,10 +454,12 @@ const init = defineCommand({
 		const generatedDirRel = path.join(serverDirRel, "generated");
 		writeFileIfAbsent(path.join(cwd, generatedDirRel, "contract.json"), "{}\n");
 		writeFileIfAbsent(path.join(cwd, generatedDirRel, "index.ts"), CONTRACT_BARREL);
+		const clientUrl = setup.siteUrl && !sameOrigin(setup.siteUrl, setup.baseUrl) ? setup.baseUrl : void 0;
 		const scaffold = {
 			serverDirName: path.basename(serverDirRel),
 			appDir: detectAppDir(cwd, hasSrcDir),
-			serverImport: (fromDir) => resolveModuleImport(cwd, serverDirRel, fromDir, setup.alias)
+			serverImport: (fromDir) => resolveModuleImport(cwd, serverDirRel, fromDir, setup.alias),
+			clientUrl
 		};
 		const clientRel = path.join(dirRel, "client.ts");
 		const clientCreated = writeFileIfAbsent(path.join(cwd, clientRel), preset.clientEntry(scaffold));
@@ -298,10 +481,20 @@ const init = defineCommand({
 		p.log.success(clientCreated ? `Created browser client (${clientRel})` : "Skipped browser client (exists)");
 		if (routeRel) p.log.success(routeCreated ? `Created API route (${routeRel})` : "Skipped API route (exists)");
 		if (gitignore !== "present") p.log.success(`${gitignore === "created" ? "Created" : "Updated"} .gitignore (ignoring .env)`);
+		if (setup.mode === "local") {
+			p.log.success(`Local WordPress configured (${setup.devPath}) — .env points at ${setup.wpUrl}`);
+			if (adminPassword) p.log.warn(`wp-admin login: ${setup.wpUsername} / ${adminPassword} — save it, it's shown only once`);
+		}
 		p.note([
-			`Watch your extensions and regenerate the contract during development:`,
-			`  npx kizlo watch`,
-			``,
+			...setup.mode === "local" ? [
+				`Start your local WordPress dev stack (also watches your extensions):`,
+				`  npx kizlo dev`,
+				``
+			] : [
+				`Watch your extensions and regenerate the contract during development:`,
+				`  npx kizlo watch`,
+				``
+			],
 			`Generate the contract once for production builds:`,
 			`  npx kizlo generate`
 		].join("\n"), "Next steps");

package/dist/cli/commands/test.js

@@ -1,7 +1,8 @@
 import { createStack } from "../wp/docker.js";
-import { isSeeded } from "../wp/utils.js";
-import { groupDefault, withSpinner } from "../utils.js";
+import { isSeeded, recordedPort } from "../wp/utils.js";
 import { log } from "../daemon/logger.js";
+import { isFree } from "../wp/ports.js";
+import { groupDefault, pickStackPort, withSpinner } from "../utils.js";
 import { resolveTestConfig } from "../daemon/config.js";
 import { testStack } from "../wp/stack.js";
 import { runSeeds } from "../wp/setup.js";
@@ -16,18 +17,57 @@ async function resolve(cwd) {
 		stack: createStack(testStack(cfg))
 	};
 }
-/** Boot the stack and seed it once (idempotent — skips seeding if already seeded). */
-async function bringUp(cfg, stack) {
-	await withSpinner("Starting WordPress test stack", () => stack.composeUp(), "WordPress test stack ready");
-	if (await isSeeded()) {
-		log.info("Stack already seeded — skipping seed.");
-		return;
+/**
+* The host port to bring the test stack up on. Unlike the dev stack (rebuilt every run), the
+* test stack is reused and its tests connect via the URL recorded in the credentials artifact —
+* so the port can't just be re-chosen each time:
+*
+* - A **running** stack keeps its live published port (fast reruns stay on the same URL).
+* - A **warm but stopped** stack reuses the port recorded in the credentials — that URL is what
+*   tests read, so it must not move; if something else stole it meanwhile we stop and say so,
+*   rather than silently relocate.
+* - Only a **cold** stack (never seeded, or wiped by `reset` / `--reset`) picks a fresh free port
+*   from the configured default — auto-stepping past a collision (e.g. another project's stack)
+*   unless `test.port` was set explicitly, in which case the user owns the clash.
+*
+* `fresh` forces the cold path so a `reset` re-picks — that's how a poisoned recorded port heals.
+*/
+async function resolveTestPort(cfg, stack, fresh) {
+	if (!fresh) {
+		const live = await stack.publishedPort();
+		if (live !== void 0) return live;
+		const recorded = recordedPort();
+		if (recorded !== void 0) {
+			if (await isFree(recorded)) return recorded;
+			log.error(`The test stack's port ${recorded} (from a previous run) is now held by something else.\nFree that port, or run \`kizlo test reset\` to rebuild on a fresh one.`);
+			process.exit(1);
+		}
 	}
-	await withSpinner("Seeding WordPress", () => runSeeds({
-		port: cfg.port,
+	return pickStackPort(cfg.port, {
+		fixed: cfg.portExplicit,
+		configKey: "test.port"
+	});
+}
+/**
+* Boot the test stack on a resolved host port and seed it once (idempotent — skips seeding when
+* already seeded). Returns the port-bound stack and the port, so callers report the real URL.
+*/
+async function bringUp(cfg, stack, fresh = false) {
+	const port = await resolveTestPort(cfg, stack, fresh);
+	const bound = port === cfg.port ? stack : createStack(testStack({
+		...cfg,
+		port
+	}));
+	await withSpinner("Starting WordPress test stack", () => bound.composeUp(), "WordPress test stack ready");
+	if (await isSeeded()) log.info("Stack already seeded — skipping seed.");
+	else await withSpinner("Seeding WordPress", () => runSeeds({
+		port,
 		fixtures: cfg.fixtures
 	}), "WordPress seeded");
-	log.success(`Stack ready on http://localhost:${cfg.port} — credentials at ${cfg.credentialsPath}`);
+	return {
+		stack: bound,
+		port
+	};
 }
 /** `<pm> test` runs the project's own test script (bun needs `run` to skip its built-in runner). */
 function testCommand(pm) {
@@ -61,13 +101,9 @@ const runArgs = {
 };
 /** Boot (+ seed) the stack, run the project's test script, then leave it up (or tear down). */
 async function runSuite({ args }) {
-	const { cfg, stack } = await resolve(process.cwd());
-	if (args.reset) await withSpinner("Wiping WordPress database", () => stack.composeDown({ volumes: true }), "Database wiped");
-	await withSpinner("Starting WordPress test stack", () => stack.composeUp(), "WordPress test stack ready");
-	if (!await isSeeded()) await withSpinner("Seeding WordPress", () => runSeeds({
-		port: cfg.port,
-		fixtures: cfg.fixtures
-	}), "WordPress seeded");
+	const { cfg, stack: probe } = await resolve(process.cwd());
+	if (args.reset) await withSpinner("Wiping WordPress database", () => probe.composeDown({ volumes: true }), "Database wiped");
+	const { stack } = await bringUp(cfg, probe, Boolean(args.reset));
 	log.info(cfg.command ? `Running: ${cfg.command}` : `Running: ${testCommand(cfg.packageManager).join(" ")}`);
 	let code = 1;
 	try {
@@ -112,7 +148,8 @@ const subCommands = {
 		async run() {
 			const { cfg, stack } = await resolve(process.cwd());
 			await withSpinner("Wiping WordPress database", () => stack.composeDown({ volumes: true }), "Database wiped");
-			await bringUp(cfg, stack);
+			const { port } = await bringUp(cfg, stack, true);
+			log.success(`Stack ready on http://localhost:${port} — credentials at ${cfg.credentialsPath}`);
 		}
 	})
 };

package/dist/cli/commands/watch.js

@@ -1,10 +1,6 @@
 import { getVersion } from "../utils.js";
-import { log } from "../daemon/logger.js";
-import { resolveConfig } from "../daemon/config.js";
-import { generateOnce } from "../daemon/generate.js";
 import { printBanner } from "../banner.js";
-import { acquire, isLocked, lockPath, release } from "../daemon/lock.js";
-import { watch as watch$1 } from "../daemon/watch.js";
+import { startWatcher } from "../daemon/watch.js";
 import { defineCommand } from "citty";
 
 //#region src/cli/commands/watch.ts
@@ -13,32 +9,18 @@ const args = { dir: {
 	description: "Override the Kizlo directory (defaults to kizlo.config.ts)"
 } };
 async function run({ args: args$1 }) {
-	const cwd = process.cwd();
-	const lock = lockPath(cwd);
-	if (isLocked(lock)) {
-		log.info("Watcher already running — nothing to do.");
-		return;
-	}
 	printBanner(getVersion());
-	const cfg = await resolveConfig(cwd, { dir: args$1.dir });
-	acquire(lock);
-	const cleanup = () => release(lock);
-	process.on("exit", cleanup);
+	const stop = await startWatcher(process.cwd(), { dir: args$1.dir });
+	if (!stop) return;
+	process.on("exit", stop);
 	for (const signal of [
 		"SIGINT",
 		"SIGTERM",
 		"SIGHUP"
 	]) process.on(signal, () => {
-		cleanup();
+		stop();
 		process.exit(0);
 	});
-	try {
-		if (await generateOnce(cfg)) log.success("Contract generated");
-		else log.warn(`No Kizlo server found in ${cfg.serverEntry}`);
-	} catch (error) {
-		log.error("Failed to generate the Kizlo contract:", error);
-	}
-	await watch$1(cfg);
 }
 const watch = defineCommand({
 	meta: {

package/dist/cli/daemon/config.js

@@ -1,6 +1,6 @@
 import { credentialsPath, findConfigDir } from "../wp/utils.js";
-import { detectPackageManager } from "../utils.js";
 import { log } from "./logger.js";
+import { detectPackageManager } from "../utils.js";
 import z from "zod/v4";
 import fs from "node:fs";
 import path from "node:path";
@@ -37,6 +37,9 @@ const CONFIG_FILES = [
 	"kizlo.config.js",
 	"kizlo.config.mjs"
 ];
+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";
 }
@@ -107,7 +110,8 @@ async function resolveTestConfig(cwd) {
 		configDir,
 		project: `${resolveStackName(configDir, fileConfig?.name)}-test`,
 		command: test.command,
-		port: test.port ?? 8889,
+		port: test.port ?? DEFAULT_TEST_PORT,
+		portExplicit: test.port !== void 0,
 		fixtures: test.fixtures ?? [],
 		credentialsPath: credentialsPath(cwd),
 		packageManager: test.packageManager ?? detectPackageManager(configDir)
@@ -134,8 +138,10 @@ async function resolveDevConfig(cwd) {
 	return {
 		configDir,
 		project: `${resolveStackName(configDir, fileConfig?.name)}-dev`,
-		port: dev.port ?? 8080,
-		dbPort: dev.dbPort ?? 3307,
+		port: dev.port ?? DEFAULT_DEV_PORT,
+		portExplicit: dev.port !== void 0,
+		dbPort: dev.dbPort ?? DEFAULT_DEV_DB_PORT,
+		dbPortExplicit: dev.dbPort !== void 0,
 		byo: dev.byo ? path.resolve(configDir, dev.byo) : void 0,
 		fixtures: dev.fixtures ?? [],
 		wordpressPath: dev.path,
@@ -144,4 +150,4 @@ async function resolveDevConfig(cwd) {
 }
 
 //#endregion
-export { resolveConfig, resolveDevConfig, resolveTestConfig };
+export { DEFAULT_DEV_DB_PORT, DEFAULT_DEV_PORT, resolveConfig, resolveDevConfig, resolveStackName, resolveTestConfig };

package/dist/cli/daemon/logger.js

@@ -3,6 +3,7 @@ import { consola } from "consola";
 //#region src/cli/daemon/logger.ts
 /** Tagged logger for the daemon — every line is prefixed with `kizlo`. */
 const log = consola.withTag("kizlo");
+log.options.formatOptions.date = false;
 
 //#endregion
 export { log };

package/dist/cli/daemon/watch.js

@@ -1,5 +1,7 @@
 import { log } from "./logger.js";
+import { resolveConfig } from "./config.js";
 import { generateOnce } from "./generate.js";
+import { acquire, isLocked, lockPath, release } from "./lock.js";
 import path from "node:path";
 import { FSWatcher } from "chokidar";
 
@@ -28,10 +30,41 @@ async function watch(cfg) {
 	});
 	const onChange = debounce(() => regenerate(cfg), 300);
 	watcher.add(path.resolve(cfg.cwd, cfg.serverDir));
-	watcher.on("ready", () => log.start("Watching for changes..."));
+	watcher.on("ready", () => log.start("Watching for contract changes..."));
 	watcher.on("all", () => void onChange());
 	return watcher;
 }
+/**
+* Acquire the single-instance lock, generate the contract once, and start the file
+* watcher. Returns a synchronous `stop()` that closes the watcher and releases the
+* lock — or `undefined` when another watcher already holds the lock (a standalone
+* `kizlo watch`, or a framework dev script), in which case the caller carries on
+* without watching. Shared by the standalone `kizlo watch` command and the
+* folded-in watcher of `kizlo dev`, so a single terminal covers both.
+*/
+async function startWatcher(cwd, opts) {
+	const lock = lockPath(cwd);
+	if (isLocked(lock)) {
+		log.info("Watcher already running — skipping the contract watcher.");
+		return;
+	}
+	const cfg = await resolveConfig(cwd, { dir: opts?.dir });
+	acquire(lock);
+	try {
+		if (await generateOnce(cfg)) log.success("Contract generated");
+		else log.warn(`No Kizlo server found in ${cfg.serverEntry}`);
+	} catch (error) {
+		log.error("Failed to generate the Kizlo contract:", error);
+	}
+	const watcher = await watch(cfg);
+	let stopped = false;
+	return () => {
+		if (stopped) return;
+		stopped = true;
+		release(lock);
+		watcher.close();
+	};
+}
 
 //#endregion
-export { watch };
+export { startWatcher };