kizlo 0.1.0 → 0.2.0

package/dist/cli/daemon/config.js

@@ -1,9 +1,9 @@
 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 path from "node:path";
 import fs from "node:fs";
+import path from "node:path";
 import { createJiti } from "jiti";
 
 //#region src/cli/daemon/config.ts
@@ -12,6 +12,14 @@ const fixtureSchema = z.custom((value) => typeof value === "object" && value !==
 const configSchema = z.object({
 	dir: z.string().optional(),
 	alias: z.string().optional(),
+	name: z.string().optional(),
+	dev: z.object({
+		path: z.string().optional(),
+		port: z.number().int().positive().optional(),
+		dbPort: z.number().int().positive().optional(),
+		byo: z.string().optional(),
+		fixtures: z.array(fixtureSchema).optional()
+	}).optional(),
 	test: z.object({
 		port: z.number().int().positive().optional(),
 		fixtures: z.array(fixtureSchema).optional(),
@@ -29,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";
 }
@@ -66,22 +77,77 @@ async function resolveConfig(cwd, flags) {
 	};
 }
 /**
+* Sanitize an arbitrary package/dir name into a valid Docker compose project id:
+* lowercase, `@scope/pkg` → `scope-pkg`, dropping anything outside `[a-z0-9_-]`.
+*/
+function sanitizeProjectName(raw) {
+	return raw.toLowerCase().replace(/^@/, "").replace(/\//g, "-").replace(/[^a-z0-9_-]/g, "").replace(/^[-_]+|[-_]+$/g, "") || "kizlo";
+}
+/**
+* Base name for the local stacks: the config `name` if set, else the `package.json`
+* `name` at `configDir`, else the config dir basename — sanitized to a Docker id.
+*/
+function resolveStackName(configDir, configName) {
+	if (configName) return sanitizeProjectName(configName);
+	let pkgName;
+	try {
+		pkgName = JSON.parse(fs.readFileSync(path.join(configDir, "package.json"), "utf8")).name;
+	} catch {
+		pkgName = void 0;
+	}
+	return sanitizeProjectName(pkgName ?? path.basename(configDir));
+}
+/**
 * Resolve the `test` block from `kizlo.config.*` into concrete values for the
-* `wp`/`test` commands, applying defaults (port 8080, auto-detected package
-* manager) and anchoring the credentials artifact to the config directory.
+* `test` command, applying defaults (port 8889, auto-detected package manager)
+* and anchoring the credentials artifact to the config directory.
 */
 async function resolveTestConfig(cwd) {
 	const configDir = findConfigDir(cwd);
-	const test = (await loadConfigFile(configDir))?.test ?? {};
+	const fileConfig = await loadConfigFile(configDir);
+	const test = fileConfig?.test ?? {};
 	return {
 		configDir,
+		project: `${resolveStackName(configDir, fileConfig?.name)}-test`,
 		command: test.command,
-		port: test.port ?? 8080,
+		port: test.port ?? DEFAULT_TEST_PORT,
+		portExplicit: test.port !== void 0,
 		fixtures: test.fixtures ?? [],
 		credentialsPath: credentialsPath(cwd),
 		packageManager: test.packageManager ?? detectPackageManager(configDir)
 	};
 }
+/**
+* Resolve the `dev` block from `kizlo.config.*` into concrete values for the `dev`
+* command, applying defaults (port 8080). `dev.path` is required — the whole
+* WordPress install lives there, so we make the user choose a real folder rather
+* than hide it under a default.
+*/
+async function resolveDevConfig(cwd) {
+	const configDir = findConfigDir(cwd);
+	const fileConfig = await loadConfigFile(configDir);
+	const dev = fileConfig?.dev ?? {};
+	if (!dev.path) {
+		log.error("`dev.path` is required in kizlo.config — it's the folder your local WordPress lives in.\nPick a real, visible folder (it persists your site between runs), e.g. dev: { path: \"wordpress\" }.");
+		process.exit(1);
+	}
+	if (dev.byo && dev.fixtures?.length) {
+		log.error("`dev.byo` and `dev.fixtures` are mutually exclusive — byo imports an existing site, so it brings its own data.");
+		process.exit(1);
+	}
+	return {
+		configDir,
+		project: `${resolveStackName(configDir, fileConfig?.name)}-dev`,
+		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,
+		wordpressDir: path.resolve(configDir, dev.path)
+	};
+}
 
 //#endregion
-export { resolveConfig, resolveTestConfig };
+export { DEFAULT_DEV_DB_PORT, DEFAULT_DEV_PORT, resolveConfig, resolveDevConfig, resolveStackName, resolveTestConfig };

package/dist/cli/daemon/generate.js

@@ -1,7 +1,7 @@
 import { generateContract } from "../../shared/contract.js";
 import { loadEnvFiles } from "../utils.js";
-import path from "node:path";
 import fs from "node:fs";
+import path from "node:path";
 import { createJiti } from "jiti";
 
 //#region src/cli/daemon/generate.ts

package/dist/cli/daemon/lock.js

@@ -1,5 +1,5 @@
-import path from "node:path";
 import fs from "node:fs";
+import path from "node:path";
 
 //#region src/cli/daemon/lock.ts
 function lockPath(cwd) {

package/dist/cli/index.js

@@ -13,7 +13,7 @@ runMain(defineCommand({
 		init: () => import("./commands/init.js").then((m) => m.init),
 		watch: () => import("./commands/watch.js").then((m) => m.watch),
 		generate: () => import("./commands/generate.js").then((m) => m.generate),
-		wp: () => import("./commands/wp.js").then((m) => m.wp),
+		dev: () => import("./commands/dev.js").then((m) => m.dev),
 		test: () => import("./commands/test.js").then((m) => m.test)
 	}
 }));

package/dist/cli/presets/base.js

@@ -3,7 +3,7 @@ const base = {
 	id: "base",
 	label: "Generic (no framework detected)",
 	detect: () => 1,
-	baseUrlEnvKey: "SERVER_BASE_URL",
+	baseUrlEnvKey: "KIZLO_BACKEND_URL",
 	serverEntry() {
 		return `import { createKizlo } from "kizlo"
 
@@ -11,6 +11,13 @@ export const { router, client, context, handler } = createKizlo()
 `;
 	},
 	clientEntry(ctx) {
+		if (ctx.clientUrl) return `import { createKizloClient } from "kizlo"
+import { contract } from "./${ctx.serverDirName}/generated"
+
+// Your Kizlo backend runs on a different origin than this app. Swap in your bundler's
+// public env var (e.g. import.meta.env.VITE_KIZLO_BACKEND_URL) to set it per environment.
+export const client = createKizloClient(contract, { url: "${ctx.clientUrl}" })
+`;
 		return `import { createKizloClient } from "kizlo"
 import { contract } from "./${ctx.serverDirName}/generated"
 

package/dist/cli/presets/nextjs.js

@@ -8,7 +8,7 @@ const nextjs = {
 			...ctx.pkg.devDependencies
 		}.next ? 100 : 0;
 	},
-	baseUrlEnvKey: "NEXT_PUBLIC_SERVER_BASE_URL",
+	baseUrlEnvKey: "NEXT_PUBLIC_KIZLO_BACKEND_URL",
 	apiPath: "/api/kizlo",
 	serverEntry() {
 		return `import { createKizlo } from "kizlo/nextjs/server"

package/dist/cli/utils.js

@@ -1,10 +1,31 @@
+import { log } from "./daemon/logger.js";
+import { PortInUseError, resolveHostPort } from "./wp/ports.js";
 import { spawnSync } from "node:child_process";
+import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import fs from "node:fs";
 import * as p from "@clack/prompts";
 
 //#region src/cli/utils.ts
+/**
+* Resolve a host port for a stack, exiting with a clear message when an *explicitly*
+* configured port (`fixed`) is already taken. A default port auto-steps to the next free
+* one (another project's stack or a stray server just shifts us over); an explicit
+* `configKey` collision is the user's own to resolve, so we stop rather than silently
+* serving on a port they didn't choose.
+*/
+async function pickStackPort(preferred, { fixed, host, configKey }) {
+	try {
+		return await resolveHostPort(preferred, {
+			fixed,
+			host
+		});
+	} catch (error) {
+		if (!(error instanceof PortInUseError)) throw error;
+		log.error(`${configKey} ${preferred} is set in kizlo.config but is already in use.\nFree that port or change ${configKey} — an explicitly set port is never auto-reassigned.`);
+		process.exit(1);
+	}
+}
 function stripJsonComments(source) {
 	return source.replace(/\\"|"(?:\\"|[^"])*"|(\/\/.*|\/\*[\s\S]*?\*\/)/g, (match, comment) => comment ? "" : match);
 }
@@ -117,11 +138,49 @@ function envKeysPresent(contents, keys) {
 	return keys.filter((key) => new RegExp(`^\\s*${key}\\s*=`, "m").test(contents));
 }
 /**
+* The grouped `.env` layout shared by `init` and `dev`, so both write the same sectioned file:
+* a target switch, the backend URL, then the production and dev connection blocks. `baseUrlEnvKey`
+* varies per preset (e.g. `NEXT_PUBLIC_KIZLO_BACKEND_URL`), so it's threaded in. Only sections whose
+* keys are actually being appended get a header, so a remote/prod run skips the dev block and vice versa.
+*/
+function envGroups(baseUrlEnvKey) {
+	return [
+		{
+			comment: "Kizlo Target (dev | prod)",
+			keys: ["KIZLO_TARGET"]
+		},
+		{
+			comment: "Kizlo Backend URL",
+			keys: [baseUrlEnvKey]
+		},
+		{
+			comment: "Kizlo Production Env",
+			keys: [
+				"KIZLO_SITE_SECRET",
+				"KIZLO_WORDPRESS_URL",
+				"KIZLO_WORDPRESS_USERNAME",
+				"KIZLO_WORDPRESS_APPLICATION_PASSWORD"
+			]
+		},
+		{
+			comment: "Kizlo Development Env",
+			keys: [
+				"KIZLO_DEV_SITE_SECRET",
+				"KIZLO_DEV_WORDPRESS_URL",
+				"KIZLO_DEV_WORDPRESS_USERNAME",
+				"KIZLO_DEV_WORDPRESS_APPLICATION_PASSWORD"
+			]
+		}
+	];
+}
+/**
 * Merges `values` into an existing .env body: other variables, comments and
 * blank lines are preserved. A managed key is rewritten only when listed in
-* `overwriteKeys`; otherwise its existing line is kept. Missing keys are appended.
+* `overwriteKeys`; otherwise its existing line is kept. Missing keys are appended —
+* grouped under their `groups` comment header (with a blank-line separator) when one
+* is given, or as bare lines otherwise.
 */
-function mergeEnv(existing, values, overwriteKeys) {
+function mergeEnv(existing, values, overwriteKeys, groups) {
 	const body = existing.replace(/\s*$/, "");
 	const lines = body.length ? body.split(/\r?\n/) : [];
 	const added = [];
@@ -140,10 +199,20 @@ function mergeEnv(existing, values, overwriteKeys) {
 		}
 		return line;
 	});
-	for (const [key, value] of Object.entries(values)) if (!present.has(key)) {
+	const remaining = new Map(Object.entries(values).filter(([key]) => !present.has(key)));
+	const append = (key) => {
 		added.push(key);
-		next.push(`${key}=${value}`);
+		next.push(`${key}=${remaining.get(key)}`);
+		remaining.delete(key);
+	};
+	for (const group of groups ?? []) {
+		const groupKeys = group.keys.filter((key) => remaining.has(key));
+		if (!groupKeys.length) continue;
+		if (next.length) next.push("");
+		next.push(`# ${group.comment}`);
+		for (const key of groupKeys) append(key);
 	}
+	for (const key of remaining.keys()) append(key);
 	return {
 		content: `${next.join("\n")}\n`,
 		added,
@@ -177,6 +246,21 @@ async function withSpinner(message, fn, done) {
 		throw error;
 	}
 }
+/**
+* Wrap a command group's default `run` so it fires only for the bare invocation
+* (`kizlo test`), not when a subcommand was given (`kizlo test up`). citty runs a
+* group's own `run` *in addition to* the matched subcommand, so without this guard
+* the default would double-fire on every subcommand. Pass the group's subcommand
+* names; the first non-flag arg is matched the same way citty picks the subcommand.
+*/
+function groupDefault(subCommandNames, run) {
+	const names = new Set(subCommandNames);
+	return async (ctx) => {
+		const sub = ctx.rawArgs.find((arg) => !arg.startsWith("-"));
+		if (sub !== void 0 && names.has(sub)) return;
+		await run(ctx);
+	};
+}
 
 //#endregion
-export { addDependencyArgs, detectImportAlias, detectPackageManager, ensureGitignored, envKeysPresent, getVersion, loadEnvFiles, mergeEnv, resolveModuleImport, runCommand, withSpinner, writeFileIfAbsent };
+export { addDependencyArgs, detectImportAlias, detectPackageManager, ensureGitignored, envGroups, envKeysPresent, getVersion, groupDefault, loadEnvFiles, mergeEnv, pickStackPort, resolveModuleImport, runCommand, withSpinner, writeFileIfAbsent };

package/dist/cli/wp/bootstrap.js

@@ -1,6 +1,6 @@
-import { ensurePlugin, resolvePluginSource } from "./utils.js";
-import { DEFAULT_PLUGINS, DEFAULT_PORT, SEED_MARKER_OPTION, SEED_VERSION, TEST_ADMIN, TEST_USER } from "./constants.js";
 import { compose, composeUp, wpCli } from "./docker.js";
+import { DEFAULT_PLUGINS, DEFAULT_PORT, SEED_MARKER_OPTION, SEED_VERSION, TEST_ADMIN, TEST_USER } from "./constants.js";
+import { ensurePlugins } from "./utils.js";
 
 //#region src/cli/wp/bootstrap.ts
 async function seedUsers() {
@@ -22,7 +22,7 @@ async function seedUsers() {
 	if (!id) throw new Error("seed/users.json must include a user with username \"user\"");
 	return Number(id);
 }
-async function createAdminAppPassword() {
+async function createAdminAppPassword(label = "harness") {
 	await compose([
 		"exec",
 		"-T",
@@ -39,7 +39,7 @@ async function createAdminAppPassword() {
 		"application-password",
 		"create",
 		TEST_ADMIN.username,
-		"harness",
+		label,
 		"--porcelain"
 	]);
 }
@@ -50,9 +50,7 @@ async function createAdminAppPassword() {
 * construct the REST client in Phase 2.
 */
 async function bootstrapWp(config) {
-	const port = config.port ?? DEFAULT_PORT;
-	const url = `http://localhost:${port}`;
-	process.env.WP_PORT = String(port);
+	const url = `http://localhost:${config.port ?? DEFAULT_PORT}`;
 	await composeUp();
 	if ((await compose([
 		"exec",
@@ -77,7 +75,7 @@ async function bootstrapWp(config) {
 		"/%postname%/",
 		"--hard"
 	]);
-	for (const plugin of [...DEFAULT_PLUGINS, ...config.fixtures?.flatMap((a) => a.plugins ?? []) ?? []]) await ensurePlugin(...resolvePluginSource(plugin));
+	await ensurePlugins([...DEFAULT_PLUGINS, ...config.fixtures?.flatMap((f) => f.plugins ?? []) ?? []]);
 	const adminId = Number(await wpCli([
 		"user",
 		"get",
@@ -88,7 +86,12 @@ async function bootstrapWp(config) {
 	const appPassword = await createAdminAppPassword();
 	await wpCli([
 		"option",
-		"update",
+		"delete",
+		SEED_MARKER_OPTION
+	]).catch(() => {});
+	await wpCli([
+		"option",
+		"add",
 		SEED_MARKER_OPTION,
 		SEED_VERSION,
 		"--autoload=no"
@@ -111,4 +114,4 @@ async function bootstrapWp(config) {
 }
 
 //#endregion
-export { bootstrapWp };
+export { bootstrapWp, createAdminAppPassword, seedUsers };

package/dist/cli/wp/byo.js

@@ -0,0 +1,113 @@
+import { execFileSync } from "node:child_process";
+import { cpSync, createReadStream, existsSync, mkdirSync, readdirSync, renameSync, rmSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { createInterface } from "node:readline";
+
+//#region src/cli/wp/byo.ts
+/** Path under the config's `.kizlo/` dir where the dump is staged for import, then deleted. */
+const SQL_STAGE_REL = ".kizlo/byo-import.sql";
+function tar(args) {
+	try {
+		return execFileSync("tar", args, {
+			encoding: "utf8",
+			maxBuffer: 64 * 1024 * 1024
+		});
+	} catch (error) {
+		const e = error;
+		throw new Error(`tar ${args.join(" ")} failed:\n${e.stderr || e.message}`);
+	}
+}
+/** Drop a leading `./` that some tar archives prefix entries with. */
+function norm(entry) {
+	return entry.replace(/^\.\//, "");
+}
+/** Move `src` to `dest`, falling back to copy+remove across filesystems (rename's EXDEV). */
+function moveInto(src, dest) {
+	try {
+		renameSync(src, dest);
+	} catch (error) {
+		if (error.code !== "EXDEV") throw error;
+		cpSync(src, dest, { recursive: true });
+		rmSync(src, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+/**
+* Validate a BYO archive and return the name of its single root-level `.sql` dump. The
+* archive must be a `.tar.gz` holding a top-level `wordpress/` directory and exactly one
+* root-level `*.sql`, and must live outside `wordpressDir` (else `reset`, which wipes
+* that folder, would delete the archive before it could be re-read).
+*/
+function validateByoArchive(archivePath, wordpressDir) {
+	if (!existsSync(archivePath)) throw new Error(`dev.byo archive not found: ${archivePath}`);
+	if (!/\.tar(\.(gz|xz|bz2|zst))?$|\.(tgz|txz|tbz2?|tzst)$/i.test(archivePath)) throw new Error(`dev.byo must be a tar archive (.tar.gz, .tar.xz, .tar.bz2, .tar.zst, .tar): ${archivePath}`);
+	if (resolve(archivePath).startsWith(resolve(wordpressDir) + sep)) throw new Error(`dev.byo archive must live outside dev.path — reset would delete it: ${archivePath}`);
+	const entries = tar(["-tf", archivePath]).split("\n").map(norm).filter(Boolean);
+	if (!entries.some((e) => e === "wordpress/" || e.startsWith("wordpress/"))) throw new Error("dev.byo archive must contain a top-level `wordpress/` directory");
+	const sqls = entries.filter((e) => /^[^/]+\.sql$/.test(e));
+	if (sqls.length !== 1) throw new Error(`dev.byo archive must contain exactly one root-level .sql file (found ${sqls.length})`);
+	return sqls[0];
+}
+/**
+* Detect the dump's table prefix from its `{prefix}options` table — the one table every
+* WordPress install has exactly one of. Streams the file and stops at the first match;
+* falls back to `wp_` when none is found (so a standard dump still imports).
+*/
+async function detectTablePrefix(sqlPath) {
+	const rl = createInterface({
+		input: createReadStream(sqlPath),
+		crlfDelay: Number.POSITIVE_INFINITY
+	});
+	try {
+		for await (const line of rl) {
+			const match = line.match(/(?:CREATE TABLE(?:\s+IF NOT EXISTS)?|INSERT INTO)\s+`?([0-9a-zA-Z$_]+?)options`?\b/i);
+			if (match) return match[1];
+		}
+	} finally {
+		rl.close();
+	}
+	return "wp_";
+}
+/**
+* Lay a BYO install onto disk before the containers boot: extract the archive, move its
+* `wordpress/` files into `wordpressDir` (dropping the bundled `wp-config.php` — the image
+* regenerates one with the compose DB credentials), stage the dump under `.kizlo/`, and
+* read its table prefix. Returns the prefix (to match the regenerated config) and the host
+* path of the staged dump (the caller pipes it into the `mysql` container, then deletes it).
+*/
+async function prepareByo(archivePath, wordpressDir, configDir) {
+	const sqlName = validateByoArchive(archivePath, wordpressDir);
+	const tmp = join(configDir, ".kizlo", "byo-extract");
+	rmSync(tmp, {
+		recursive: true,
+		force: true
+	});
+	mkdirSync(tmp, { recursive: true });
+	try {
+		tar([
+			"-xf",
+			archivePath,
+			"-C",
+			tmp
+		]);
+		mkdirSync(wordpressDir, { recursive: true });
+		for (const entry of readdirSync(join(tmp, "wordpress"))) moveInto(join(tmp, "wordpress", entry), join(wordpressDir, entry));
+		rmSync(join(wordpressDir, "wp-config.php"), { force: true });
+		const sqlPath = join(configDir, SQL_STAGE_REL);
+		moveInto(join(tmp, sqlName), sqlPath);
+		return {
+			prefix: await detectTablePrefix(sqlPath),
+			sqlPath
+		};
+	} finally {
+		rmSync(tmp, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+
+//#endregion
+export { prepareByo };

package/dist/cli/wp/compose/docker-compose.yml

@@ -1,5 +1,4 @@
-name: kizlo-wp-test
-
+# Project name is supplied per-stack via `docker compose -p <project>`.
 services:
   mysql:
     image: mysql:8
@@ -36,8 +35,20 @@ services:
       WORDPRESS_DB_NAME: ${MYSQL_DATABASE:-wordpress}
       WORDPRESS_DB_USER: ${MYSQL_USER:-wordpress}
       WORDPRESS_DB_PASSWORD: ${MYSQL_PASSWORD:-wppass}
+      # The wordpress image eval()s WORDPRESS_CONFIG_EXTRA at runtime, and Compose
+      # interpolates `$` in this file first — so every PHP variable below is written
+      # `$$` to survive Compose and reach PHP as a literal `$`.
       WORDPRESS_CONFIG_EXTRA: |
         define('WP_ENVIRONMENT_TYPE', 'local');
+        // Dev only: serve under whatever host the request came in on (localhost or a LAN
+        // IP) instead of the stored siteurl, so the stack is reachable from other devices
+        // on the network, like `next dev`. CLI requests have no HTTP_HOST and fall back to
+        // the database value, so wp-cli/bootstrap stay on the canonical URL.
+        if (!empty($$_SERVER['HTTP_HOST'])) {
+          $$kizlo_scheme = (!empty($$_SERVER['HTTPS']) && $$_SERVER['HTTPS'] !== 'off') ? 'https://' : 'http://';
+          define('WP_HOME', $$kizlo_scheme . $$_SERVER['HTTP_HOST']);
+          define('WP_SITEURL', $$kizlo_scheme . $$_SERVER['HTTP_HOST']);
+        }
     volumes:
       - wp_data:/var/www/html
     healthcheck:

package/dist/cli/wp/compose/opcache.ini

@@ -0,0 +1,16 @@
+; Kizlo dev — PHP OPcache tuned for local development.
+;
+; OPcache keeps compiled PHP bytecode in memory, so WordPress skips re-reading and
+; recompiling its hundreds of files on every request — the single biggest speedup
+; when the install is bind-mounted from the host.
+;
+; validate_timestamps=1 (with revalidate_freq=0) makes OPcache re-check each file's
+; mtime every request, so live edits from a bind mount show up immediately. Never
+; set this to 0 in dev or your changes will appear "stuck" behind a stale cache.
+opcache.enable=1
+opcache.enable_cli=0
+opcache.memory_consumption=128
+opcache.interned_strings_buffer=16
+opcache.max_accelerated_files=10000
+opcache.validate_timestamps=1
+opcache.revalidate_freq=0

package/dist/cli/wp/compose/override.js

@@ -0,0 +1,104 @@
+import { OPCACHE_INI, REMAP_ENTRYPOINT } from "../constants.js";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, resolve } from "node:path";
+
+//#region src/cli/wp/compose/override.ts
+/** Generated dev override location, relative to the config root. */
+const OVERRIDE_REL = ".kizlo/docker-compose.dev.override.yml";
+/** Generated test override location (plugin mounts only), relative to the config root. */
+const TEST_OVERRIDE_REL = ".kizlo/docker-compose.test.override.yml";
+const WP_ROOT = "/var/www/html";
+const PLUGINS_DIR = `${WP_ROOT}/wp-content/plugins`;
+/** Where the dev OPcache config is dropped so the container's PHP picks it up. */
+const PHP_CONF_TARGET = "/usr/local/etc/php/conf.d/zz-kizlo-opcache.ini";
+/** Where the Linux uid-remap entrypoint is mounted (run via `sh`, so no +x needed). */
+const REMAP_TARGET = "/usr/local/bin/kizlo-remap-entrypoint.sh";
+function renderService(name, block) {
+	const lines = [`  ${name}:`];
+	if (block.user) lines.push(`    user: "${block.user}"`);
+	if (block.entrypoint) lines.push(`    entrypoint: ${JSON.stringify(block.entrypoint)}`);
+	if (block.env) {
+		lines.push("    environment:");
+		for (const [key, value] of Object.entries(block.env)) lines.push(`      ${key}: "${value}"`);
+	}
+	if (block.ports?.length) lines.push("    ports:", ...block.ports.map((p) => `      - "${p}"`));
+	if (block.volumes?.length) lines.push("    volumes:", ...block.volumes);
+	return lines.join("\n");
+}
+/**
+* A compose volume line (`- "host:container"`). `:ro` marks it read-only — the
+* container can read it but never write back to the host file.
+*/
+function bind(host, container, readOnly = false) {
+	return `      - "${host}:${container}${readOnly ? ":ro" : ""}"`;
+}
+/** Resolve each local-plugin dir to a volume bind under `wp-content/plugins`, layered by basename. */
+function pluginBinds(configDir, mounts) {
+	return mounts.map((entry) => bind(isAbsolute(entry) ? entry : resolve(configDir, entry), `${PLUGINS_DIR}/${basename(entry)}`));
+}
+/**
+* Generate the dev compose override. The whole install is bind-mounted from the
+* host `wordpressDir`, so every file is live and editable; local plugin dirs layer
+* on top by basename; and the dev OPcache config is dropped into PHP (a speed win
+* with live-edit-safe settings). Binds apply to both `wordpress` (serves the site)
+* and `wp-cli` (activates plugins). On Linux (`hostUser` set) the container also
+* runs as the host user so generated files are owned by you, not uid 33. Returns
+* the override path to append to the dev stack's compose files.
+*/
+function writeDevOverride(configDir, opts) {
+	const path$1 = resolve(configDir, OVERRIDE_REL);
+	mkdirSync(dirname(path$1), { recursive: true });
+	mkdirSync(opts.wordpressDir, { recursive: true });
+	const mounts = pluginBinds(configDir, opts.mounts);
+	const rootBind = bind(opts.wordpressDir, WP_ROOT);
+	const remap = opts.hostUser ? {
+		wordpress: {
+			user: "0:0",
+			entrypoint: ["sh", REMAP_TARGET],
+			env: {
+				KIZLO_PUID: String(opts.hostUser.uid),
+				KIZLO_PGID: String(opts.hostUser.gid)
+			},
+			scriptBind: bind(REMAP_ENTRYPOINT, REMAP_TARGET, true)
+		},
+		wpCliUser: `${opts.hostUser.uid}:${opts.hostUser.gid}`
+	} : void 0;
+	const wordpress = {
+		user: remap?.wordpress.user,
+		entrypoint: remap?.wordpress.entrypoint,
+		env: remap?.wordpress.env,
+		volumes: [
+			...remap ? [remap.wordpress.scriptBind] : [],
+			rootBind,
+			...mounts,
+			bind(OPCACHE_INI, PHP_CONF_TARGET, true)
+		]
+	};
+	const wpCli = {
+		user: remap?.wpCliUser,
+		volumes: [rootBind, ...mounts]
+	};
+	const services = [renderService("wordpress", wordpress), renderService("wp-cli", wpCli)];
+	if (opts.dbPort) services.push(renderService("mysql", { ports: [`127.0.0.1:${opts.dbPort}:3306`] }));
+	writeFileSync(path$1, `services:\n${services.join("\n")}\n`);
+	return path$1;
+}
+/**
+* Generate the test compose override: bind-mount the fixtures' local plugin dirs over
+* `wp-content/plugins` (by basename) on both `wordpress` and `wp-cli`, layered on top of
+* the test stack's `wp_data` volume. Unlike the dev override it touches nothing else —
+* the test stack keeps its volume-backed install, OPcache, and default entrypoints — so a
+* fixture carrying a `{ path }` plugin runs against your live source with no build/zip
+* step, exactly as in `kizlo dev`. Returns the override path to append to the test stack's
+* compose files.
+*/
+function writeTestOverride(configDir, mounts) {
+	const path$1 = resolve(configDir, TEST_OVERRIDE_REL);
+	mkdirSync(dirname(path$1), { recursive: true });
+	const binds = pluginBinds(configDir, mounts);
+	writeFileSync(path$1, `services:\n${[renderService("wordpress", { volumes: binds }), renderService("wp-cli", { volumes: binds })].join("\n")}\n`);
+	return path$1;
+}
+
+//#endregion
+export { writeDevOverride, writeTestOverride };