kizlo 0.1.0 → 0.2.0

package/dist/cli/commands/init.js

@@ -1,23 +1,64 @@
-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 { 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 { CONTRACT_BARREL } from "../daemon/generate.js";
 import { PRESETS, detectPreset, getPreset } from "../presets/index.js";
 import z from "zod/v4";
 import { randomBytes } from "node:crypto";
-import path from "node:path";
 import fs from "node:fs";
+import path from "node:path";
 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,6 +368,10 @@ 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}`);
@@ -226,14 +380,26 @@ const init = defineCommand({
 			if (!ok) p.log.warn(`Install it yourself: ${addDependencyArgs(pm, "kizlo").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,7 +481,16 @@ 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([
+			...setup.mode === "local" ? [
+				`Start your local WordPress dev stack:`,
+				`  npx kizlo dev`,
+				``
+			] : [],
 			`Watch your extensions and regenerate the contract during development:`,
 			`  npx kizlo watch`,
 			``,

package/dist/cli/commands/test.js

@@ -1,13 +1,74 @@
-import { isSeeded } from "../wp/utils.js";
-import { composeDown, composeUp } from "../wp/docker.js";
-import { withSpinner } from "../utils.js";
+import { createStack } from "../wp/docker.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";
 import { spawn } from "node:child_process";
 import { defineCommand } from "citty";
 
 //#region src/cli/commands/test.ts
+async function resolve(cwd) {
+	const cfg = await resolveTestConfig(cwd);
+	return {
+		cfg,
+		stack: createStack(testStack(cfg))
+	};
+}
+/**
+* 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);
+		}
+	}
+	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");
+	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) {
 	return pm === "bun" ? [
@@ -23,45 +84,83 @@ function spawnTest(command, pm) {
 		stdio: "inherit",
 		shell: command !== void 0 || process.platform === "win32"
 	});
-	return new Promise((resolve, reject) => {
+	return new Promise((resolvePromise, reject) => {
 		child.on("error", reject);
-		child.on("close", (code) => resolve(code ?? 0));
+		child.on("close", (code) => resolvePromise(code ?? 0));
 	});
 }
-const test = defineCommand({
-	meta: {
-		name: "test",
-		description: "Boot the WordPress test stack (if needed), seed it, and run your tests against it"
+const runArgs = {
+	teardown: {
+		type: "boolean",
+		description: "Tear down the test stack after tests finish (default: leave it running for fast reruns)"
 	},
-	args: {
-		teardown: {
-			type: "boolean",
-			description: "Tear down the test stack after tests finish (default: leave it running for fast reruns)"
+	reset: {
+		type: "boolean",
+		description: "Wipe the database and reseed before running"
+	}
+};
+/** Boot (+ seed) the stack, run the project's test script, then leave it up (or tear down). */
+async function runSuite({ args }) {
+	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 {
+		code = await spawnTest(cfg.command, cfg.packageManager);
+	} finally {
+		if (args.teardown) await withSpinner("Tearing down WordPress test stack", () => stack.composeDown(), "WordPress test stack stopped");
+		else log.info("Stack left running for fast reruns — `kizlo test stop` to stop it, or rerun with --teardown.");
+	}
+	process.exit(code);
+}
+const subCommands = {
+	stop: defineCommand({
+		meta: {
+			name: "stop",
+			description: "Stop the WordPress test stack, keeping the database volume"
+		},
+		async run() {
+			const { stack } = await resolve(process.cwd());
+			await withSpinner("Stopping WordPress test stack", () => stack.composeStop(), "Stack stopped (volumes kept)");
+		}
+	}),
+	down: defineCommand({
+		meta: {
+			name: "down",
+			description: "Stop and remove the test stack containers"
 		},
-		reset: {
+		args: { volumes: {
 			type: "boolean",
-			description: "Wipe the database and reseed before running"
+			alias: "v",
+			description: "Also drop the database volume"
+		} },
+		async run({ args }) {
+			const { stack } = await resolve(process.cwd());
+			await withSpinner("Removing WordPress test stack", () => stack.composeDown({ volumes: args.volumes }), args.volumes ? "Stack removed (volumes dropped)" : "Stack removed (volumes kept)");
 		}
-	},
-	async run({ args }) {
-		const cfg = await resolveTestConfig(process.cwd());
-		process.env.WP_PORT = String(cfg.port);
-		if (args.reset) await withSpinner("Wiping WordPress database", () => composeDown({ volumes: true }), "Database wiped");
-		await withSpinner("Starting WordPress test stack", composeUp, "WordPress test stack ready");
-		if (!await isSeeded()) await withSpinner("Seeding WordPress", () => runSeeds({
-			port: cfg.port,
-			fixtures: cfg.fixtures
-		}), "WordPress seeded");
-		log.info(cfg.command ? `Running: ${cfg.command}` : `Running: ${testCommand(cfg.packageManager).join(" ")}`);
-		let code = 1;
-		try {
-			code = await spawnTest(cfg.command, cfg.packageManager);
-		} finally {
-			if (args.teardown) await withSpinner("Tearing down WordPress test stack", () => composeDown(), "WordPress test stack stopped");
-			else log.info("Stack left running for fast reruns — `kizlo wp stop` to stop it, or rerun with --teardown.");
+	}),
+	reset: defineCommand({
+		meta: {
+			name: "reset",
+			description: "Wipe the database and reseed a fresh WordPress test stack"
+		},
+		async run() {
+			const { cfg, stack } = await resolve(process.cwd());
+			await withSpinner("Wiping WordPress database", () => stack.composeDown({ volumes: true }), "Database wiped");
+			const { port } = await bringUp(cfg, stack, true);
+			log.success(`Stack ready on http://localhost:${port} — credentials at ${cfg.credentialsPath}`);
 		}
-		process.exit(code);
-	}
+	})
+};
+const test = defineCommand({
+	meta: {
+		name: "test",
+		description: "Manage the WordPress test stack and run tests (stop | down | reset)"
+	},
+	args: runArgs,
+	subCommands,
+	run: groupDefault(Object.keys(subCommands), runSuite)
 });
 
 //#endregion

package/dist/cli/commands/watch.js

@@ -1,8 +1,8 @@
-import { getVersion } from "../utils.js";
 import { log } from "../daemon/logger.js";
+import { getVersion } from "../utils.js";
+import { printBanner } from "../banner.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 { defineCommand } from "citty";