kizlo 0.1.1 → 0.2.1

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,3 +1,5 @@
+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";
@@ -5,6 +7,25 @@ import { fileURLToPath } from "node:url";
 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,
@@ -194,4 +263,4 @@ function groupDefault(subCommandNames, run) {
 }
 
 //#endregion
-export { addDependencyArgs, detectImportAlias, detectPackageManager, ensureGitignored, envKeysPresent, getVersion, groupDefault, 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/compose/docker-compose.yml

@@ -35,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/dev.js

@@ -1,6 +1,6 @@
 import { WordPressService } from "../../wordpress/service.js";
 import { compose, composeUp, wpCli } from "./docker.js";
-import { TEST_ADMIN } from "./constants.js";
+import { DEFAULT_PLUGINS, TEST_ADMIN } from "./constants.js";
 import { ensurePlugins } from "./utils.js";
 import { createAdminAppPassword, seedUsers } from "./bootstrap.js";
 import { prepareByo } from "./byo.js";
@@ -128,14 +128,16 @@ async function bootstrapDev(cfg) {
 			"--hard"
 		]);
 	}
-	await ensurePlugins(cfg.fixtures.flatMap((fixture) => fixture.plugins ?? []));
+	await ensurePlugins([...DEFAULT_PLUGINS, ...cfg.fixtures.flatMap((fixture) => fixture.plugins ?? [])]);
 	const seeded = !installed && !byo && cfg.fixtures.length ? await seedDevFixtures(cfg, url) : 0;
+	const appPassword = password ? await createAdminAppPassword("kizlo-dev") : void 0;
 	return {
 		url,
 		username: TEST_ADMIN.username,
 		dbPort: cfg.dbPort,
 		imported,
 		seeded,
+		appPassword,
 		secrets: password ? { password } : void 0
 	};
 }

package/dist/cli/wp/docker.d.ts

@@ -1,8 +1,14 @@
 //#region src/cli/wp/docker.d.ts
-/** Input piped to a command's stdin: an in-memory string, or a file streamed from disk. */
+/**
+ * Options for a spawned docker command.
+ * - `input`/`inputFile`: data piped to stdin (an in-memory string, or a file streamed from disk).
+ * - `detached`: run in its own process group so a terminal Ctrl+C (delivered to the whole
+ *   foreground group) can't kill it mid-flight — used for teardown's `stop`, which must finish.
+ */
 type RunInput = {
   input?: string;
   inputFile?: string;
+  detached?: boolean;
 };
 /** A docker-compose stack: project id (`-p`), published port, and compose files (`-f`). */
 interface Stack {
@@ -17,10 +23,14 @@ interface Stack {
 interface DockerStack {
   compose(args: string[], opts?: RunInput): Promise<RunResult>;
   composeUp(): Promise<void>;
-  composeStop(): Promise<void>;
+  composeStop(opts?: {
+    detached?: boolean;
+  }): Promise<void>;
   composeDown(opts?: {
     volumes?: boolean;
   }): Promise<void>;
+  /** The host port this stack's WordPress is currently published on, or `undefined` if it isn't running. */
+  publishedPort(): Promise<number | undefined>;
   wpCli(args: string[]): Promise<string>;
 }
 interface RunResult {
@@ -28,6 +38,12 @@ interface RunResult {
   stdout: string;
   stderr: string;
 }
+/**
+ * Whether the Docker daemon is reachable. `docker version` contacts the server (not just
+ * the client), so a non-zero exit means the daemon is down or Docker isn't installed —
+ * the early check before a command that needs a stack (e.g. `init`'s local setup).
+ */
+declare function dockerAvailable(): Promise<boolean>;
 /** Build a stack-bound docker helper and mark it active for the bare helpers below. */
 declare function createStack(stack: Stack): DockerStack;
 /** `docker compose <args>` against the active stack. */
@@ -39,8 +55,10 @@ declare const composeDown: (opts?: {
   volumes?: boolean;
 }) => Promise<void>;
 /** `docker compose stop` — halt the active stack's containers but keep volumes. */
-declare const composeStop: () => Promise<void>;
+declare const composeStop: (opts?: {
+  detached?: boolean;
+}) => Promise<void>;
 /** Run a wp-cli command against the active stack's warm `wp-cli` container. */
 declare const wpCli: (args: string[]) => Promise<string>;
 //#endregion
-export { DockerStack, RunResult, Stack, compose, composeDown, composeStop, composeUp, createStack, wpCli };
+export { DockerStack, RunResult, Stack, compose, composeDown, composeStop, composeUp, createStack, dockerAvailable, wpCli };

package/dist/cli/wp/docker.js

@@ -10,7 +10,8 @@ function run(cmd, args, env, opts) {
 				"pipe",
 				"pipe"
 			],
-			env
+			env,
+			detached: opts?.detached
 		});
 		let stdout = "";
 		let stderr = "";
@@ -31,6 +32,18 @@ function run(cmd, args, env, opts) {
 		else child.stdin.end();
 	});
 }
+/**
+* Whether the Docker daemon is reachable. `docker version` contacts the server (not just
+* the client), so a non-zero exit means the daemon is down or Docker isn't installed —
+* the early check before a command that needs a stack (e.g. `init`'s local setup).
+*/
+async function dockerAvailable() {
+	try {
+		return (await run("docker", ["version"], process.env)).code === 0;
+	} catch {
+		return false;
+	}
+}
 function bind(stack) {
 	const base = [
 		"compose",
@@ -56,8 +69,16 @@ function bind(stack) {
 		if (opts?.volumes) args.push("-v");
 		await compose$1(args);
 	};
-	const composeStop$1 = async () => {
-		await compose$1(["stop"]);
+	const composeStop$1 = async (opts) => {
+		await compose$1(["stop"], opts);
+	};
+	const publishedPort = async () => {
+		const match = (await compose$1([
+			"port",
+			"wordpress",
+			"80"
+		])).stdout.match(/:(\d+)\s*$/);
+		return match ? Number(match[1]) : void 0;
 	};
 	const wpCli$1 = async (args) => {
 		const res = await compose$1([
@@ -75,6 +96,7 @@ function bind(stack) {
 		composeUp: composeUp$1,
 		composeStop: composeStop$1,
 		composeDown: composeDown$1,
+		publishedPort,
 		wpCli: wpCli$1
 	};
 }
@@ -100,9 +122,9 @@ const composeUp = () => activeStack().composeUp();
 /** Tear the active stack down, optionally removing volumes. */
 const composeDown = (opts) => activeStack().composeDown(opts);
 /** `docker compose stop` — halt the active stack's containers but keep volumes. */
-const composeStop = () => activeStack().composeStop();
+const composeStop = (opts) => activeStack().composeStop(opts);
 /** Run a wp-cli command against the active stack's warm `wp-cli` container. */
 const wpCli = (args) => activeStack().wpCli(args);
 
 //#endregion
-export { compose, composeDown, composeStop, composeUp, createStack, wpCli };
+export { compose, composeDown, composeStop, composeUp, createStack, dockerAvailable, wpCli };

package/dist/cli/wp/ports.js

@@ -0,0 +1,72 @@
+import { createServer } from "node:net";
+
+//#region src/cli/wp/ports.ts
+/** Thrown when an explicitly-configured port is already taken — a collision the user owns. */
+var PortInUseError = class extends Error {
+	port;
+	host;
+	constructor(port, host) {
+		super(`Port ${host}:${port} is already in use`);
+		this.name = "PortInUseError";
+		this.port = port;
+		this.host = host;
+	}
+};
+/** True if `host:port` can be bound right now (i.e. nothing else is listening on it). */
+function isFree(port, host = "0.0.0.0") {
+	return new Promise((resolvePromise) => {
+		const server = createServer();
+		server.once("error", () => resolvePromise(false));
+		server.listen({
+			port,
+			host
+		}, () => server.close(() => resolvePromise(true)));
+	});
+}
+/** An OS-assigned ephemeral port on `host` — the fallback when the whole scan range is taken. */
+function ephemeralPort(host) {
+	return new Promise((resolvePromise, reject) => {
+		const server = createServer();
+		server.once("error", reject);
+		server.listen({
+			port: 0,
+			host
+		}, () => {
+			const address = server.address();
+			const port = typeof address === "object" && address ? address.port : 0;
+			server.close(() => resolvePromise(port));
+		});
+	});
+}
+/**
+* Resolve `preferred` to a host port that's actually free, scanning upward from it.
+* The configured/default value is only a *starting point*: if it (or the next few) are
+* already taken — by a stray container, another stack, or any unrelated server — we step
+* to the next free port instead of letting `docker compose up` fail with a port clash.
+* Falls back to an OS-assigned ephemeral port if the whole scan range is busy.
+*
+* `host` must match how the port is published: `0.0.0.0` for the all-interfaces WP port,
+* `127.0.0.1` for the loopback-only MySQL port — a port can be free on one and not the other.
+*/
+async function findFreePort(preferred, host = "0.0.0.0") {
+	for (let port = preferred; port < preferred + 100; port++) if (await isFree(port, host)) return port;
+	return ephemeralPort(host);
+}
+/**
+* Resolve a host port, branching on whether the value was *chosen by the user*:
+*
+* - A **default** port (`fixed: false`) is only a starting point — if it's taken (by another
+*   project's stack or any unrelated server) we step to the next free one via {@link findFreePort},
+*   so the stack comes up instead of failing on a clash.
+* - An **explicit** port (`fixed: true`, set in `kizlo.config`) is the user taking control: a
+*   collision there is theirs to resolve, so we throw {@link PortInUseError} rather than silently
+*   serving somewhere they didn't ask for.
+*/
+async function resolveHostPort(preferred, { fixed, host = "0.0.0.0" }) {
+	if (!fixed) return findFreePort(preferred, host);
+	if (await isFree(preferred, host)) return preferred;
+	throw new PortInUseError(preferred, host);
+}
+
+//#endregion
+export { PortInUseError, isFree, resolveHostPort };

package/dist/cli/wp/session.js

@@ -0,0 +1,150 @@
+import { execFile, spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { homedir } from "node:os";
+
+//#region src/cli/wp/session.ts
+const exec = promisify(execFile);
+/**
+* Where foreground `kizlo dev` sessions are recorded, keyed by compose project.
+* Global (not per-repo) on purpose: the whole point is to reap a *different*
+* project's stack that was orphaned by a crashed session you never came back to.
+*/
+function registryPath() {
+	return join(homedir(), ".cache", "kizlo", "dev-sessions.json");
+}
+function readRegistry() {
+	const file = registryPath();
+	if (!existsSync(file)) return {};
+	try {
+		return JSON.parse(readFileSync(file, "utf8"));
+	} catch {
+		return {};
+	}
+}
+function writeRegistry(registry) {
+	const file = registryPath();
+	mkdirSync(dirname(file), { recursive: true });
+	writeFileSync(file, JSON.stringify(registry, null, 2));
+}
+/** True when a process with this PID is still alive (signal 0 probes without killing). */
+function pidAlive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Stop a compose project's containers by label, without needing its compose files.
+* Used for orphans owned by a dead PID — we can't assume we're in that project's
+* directory, so we target the running containers directly rather than via compose.
+*/
+async function stopByProject(project) {
+	const { stdout } = await exec("docker", [
+		"ps",
+		"-q",
+		"--filter",
+		`label=com.docker.compose.project=${project}`
+	]);
+	const ids = stdout.split("\n").filter(Boolean);
+	if (ids.length) await exec("docker", ["stop", ...ids]);
+}
+/**
+* Stop and remove *every* container for `project` — running or stopped — keeping its
+* volumes (the DB and bind-mounted install survive). Run right before bringing a dev
+* stack up so `compose up` creates brand-new containers instead of reconciling a stale
+* one left by a crashed session or a second invocation: reconciling an existing — often
+* unhealthy — mysql in place is what intermittently fails the dependency wait with
+* "exited (137)". Returns true if it removed anything. Best effort: a docker-down error
+* surfaces later on `up`, where the message is actionable.
+*/
+async function removeProjectContainers(project) {
+	try {
+		const { stdout } = await exec("docker", [
+			"ps",
+			"-aq",
+			"--filter",
+			`label=com.docker.compose.project=${project}`
+		]);
+		const ids = stdout.split("\n").filter(Boolean);
+		if (!ids.length) return false;
+		await exec("docker", ["stop", ...ids]).catch(() => {});
+		await exec("docker", [
+			"rm",
+			"-f",
+			...ids
+		]);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Spawn the detached watchdog that stops `project`'s stack when this process dies by
+* any means the in-process handlers can't catch (terminal closed, SIGKILL, crash).
+* Returns its PID so the graceful teardown path can kill it (the stack is already
+* being stopped, so the watchdog would have nothing to do). Best effort: a failure
+* here just means we fall back to signal handlers + the startup reaper.
+*/
+function spawnWatchdog(project) {
+	try {
+		const watchdog = fileURLToPath(new URL("./watchdog.js", import.meta.url));
+		const child = spawn(process.execPath, [
+			watchdog,
+			String(process.pid),
+			project
+		], {
+			detached: true,
+			stdio: "ignore"
+		});
+		child.unref();
+		return child.pid;
+	} catch {
+		return;
+	}
+}
+/** Record this process as the owner of `project`'s foreground stack. */
+function registerSession(project) {
+	const registry = readRegistry();
+	registry[project] = { pid: process.pid };
+	writeRegistry(registry);
+}
+/** Drop `project` from the registry (graceful teardown). Best effort. */
+function unregisterSession(project) {
+	try {
+		const registry = readRegistry();
+		if (registry[project]) {
+			delete registry[project];
+			writeRegistry(registry);
+		}
+	} catch {}
+}
+/**
+* Stop any foreground stacks whose owning session has died (SIGKILL, crash, power
+* loss) — the cases a signal handler can never catch. Runs at the start of every
+* `kizlo dev`, so leaked stacks from *any* project self-heal the next time you
+* bring one up. Returns the projects that were reaped, for logging.
+*/
+async function reapOrphans() {
+	const registry = readRegistry();
+	const reaped = [];
+	let changed = false;
+	for (const [project, session] of Object.entries(registry)) {
+		if (pidAlive(session.pid)) continue;
+		try {
+			await stopByProject(project);
+			reaped.push(project);
+		} catch {}
+		delete registry[project];
+		changed = true;
+	}
+	if (changed) writeRegistry(registry);
+	return reaped;
+}
+
+//#endregion
+export { reapOrphans, registerSession, removeProjectContainers, spawnWatchdog, unregisterSession };

package/dist/cli/wp/settings.js

@@ -0,0 +1,73 @@
+import { WP_KIZLO_BASE } from "../../wordpress/constants.js";
+import { WordPressService } from "../../wordpress/service.js";
+
+//#region src/cli/wp/settings.ts
+/** Loopback hosts that, from inside the dev Docker stack, must be rewritten to reach the host. */
+const LOOPBACK_HOSTS = new Set([
+	"localhost",
+	"127.0.0.1",
+	"0.0.0.0",
+	"::1"
+]);
+/** The origin of a URL (scheme + host + port), or undefined when it can't be parsed. */
+function originOf(url) {
+	try {
+		return new URL(url).origin;
+	} catch {
+		return;
+	}
+}
+/**
+* Rewrite a loopback host to `host.docker.internal` so the dockerized WordPress dev stack can reach a
+* Kizlo server on the host (the container's own `localhost` is not the host). Non-loopback hosts (real
+* deployments) and unparseable URLs are returned unchanged.
+*/
+function toContainerHostUrl(url) {
+	try {
+		const parsed = new URL(url);
+		if (!LOOPBACK_HOSTS.has(parsed.hostname)) return url;
+		parsed.hostname = "host.docker.internal";
+		return parsed.toString();
+	} catch {
+		return url;
+	}
+}
+/**
+* Push site-level settings into the WordPress plugin's `kizlo_settings_site` option: the shared
+* `secret` (so webhook signing/verification share a key) plus the `url`/`backend_url` the plugin
+* needs to reach the Kizlo server when delivering events. `backend_url` is the backend URL verbatim;
+* `url` is an explicit `siteUrl` when given (split deployments), otherwise the backend's origin (the
+* single-origin default used by dev + local provision). `PUT /kizlo/v1/settings/site` merges, so
+* sending only the keys we have is a safe partial update that leaves other site settings intact;
+* empty fields are omitted. Best-effort: the plugin may not be active yet (remote `init`), so
+* failures are returned, never thrown.
+*/
+async function syncSiteSettings(credentials, settings) {
+	const body = {};
+	if (settings.secret) body.secret = settings.secret;
+	const url = settings.siteUrl ?? (settings.backendUrl ? originOf(settings.backendUrl) : void 0);
+	if (settings.backendUrl) body.backend_url = settings.containerized ? toContainerHostUrl(settings.backendUrl) : settings.backendUrl;
+	if (url) body.url = url;
+	const response = await new WordPressService({ credentials }).put("settings/site", {
+		base: WP_KIZLO_BASE,
+		body
+	});
+	if (response.error) return {
+		ok: false,
+		error: describeError(response.status, response.error)
+	};
+	return { ok: true };
+}
+/**
+* A short, log-friendly summary of a failed request. A transport failure has no HTTP status (`0`), so
+* its message (e.g. `fetch failed`) is the only signal; otherwise the status code is shown — the raw
+* `error.message` can be a full HTML page (when the URL serves the frontend instead of WordPress) and
+* would flood the warning.
+*/
+function describeError(status, error) {
+	if (status === 0) return error.message;
+	return `HTTP ${status}`;
+}
+
+//#endregion
+export { syncSiteSettings };

package/dist/cli/wp/types.d.ts

@@ -68,6 +68,8 @@ type LocalPlugin = {
 type DevPluginSource = PluginSource | LocalPlugin;
 /** True when a dev plugin entry is a local directory to bind-mount, not something to install. */
 declare function isLocalPlugin(plugin: DevPluginSource): plugin is LocalPlugin;
+type FixtureSeedFn = (ctx: SeedContext) => Promise<Record<string, JsonValue>>;
+type FixtureCleanupFn = (ctx: SeedContext) => Promise<void>;
 /** The serializable test layer an extension ships alongside its live extension. */
 interface Fixture {
   /** Namespace key under `TestCredentials.fixtures`. */
@@ -81,11 +83,11 @@ interface Fixture {
    */
   plugins?: DevPluginSource[];
   /** Build this extension's world once during seeding; return created handles. */
-  seed?: (ctx: SeedContext) => Promise<Record<string, JsonValue>>;
+  seed?: FixtureSeedFn;
   /** Revert per-test mutations (teardown); does NOT uninstall plugins or seeded data. */
-  cleanup?: (ctx: SeedContext) => Promise<void>;
+  cleanup?: FixtureCleanupFn;
 }
 /** Identity helper for authoring a `Fixture` with full inference and autocomplete. */
 declare function defineFixture(fixture: Fixture): Fixture;
 //#endregion
-export { DevPluginSource, Fixture, JsonValue, LocalPlugin, PluginSource, SeedContext, TestAdminUser, TestCredentials, TestUser, defineFixture, isLocalPlugin };
+export { DevPluginSource, Fixture, FixtureCleanupFn, FixtureSeedFn, JsonValue, LocalPlugin, PluginSource, SeedContext, TestAdminUser, TestCredentials, TestUser, defineFixture, isLocalPlugin };

package/dist/cli/wp/utils.d.ts

@@ -56,5 +56,11 @@ declare function findConfigDir(cwd?: string): string;
 /** Fixed credentials artifact path, anchored to the config root. */
 declare function credentialsPath(cwd?: string): string;
 declare function getTestCredentials(): TestCredentials;
+/**
+ * The host port the credentials artifact advertises, if it exists — the port a warm test
+ * stack is pinned to. Tests connect via this URL, so a reused stack must come back up on
+ * the same port; `undefined` means no stack has ever been seeded here (a cold boot).
+ */
+declare function recordedPort(): number | undefined;
 //#endregion
-export { activateLocalPlugin, credentialsPath, ensurePlugin, ensurePlugins, findConfigDir, getTestCredentials, githubRelease, isSeeded, kizloRelease, resolvePluginSource };
+export { activateLocalPlugin, credentialsPath, ensurePlugin, ensurePlugins, findConfigDir, getTestCredentials, githubRelease, isSeeded, kizloRelease, recordedPort, resolvePluginSource };

package/dist/cli/wp/utils.js

@@ -142,6 +142,22 @@ function getTestCredentials() {
 	cached = JSON.parse(readFileSync(credentialsPath(), "utf-8"));
 	return cached;
 }
+/**
+* The host port the credentials artifact advertises, if it exists — the port a warm test
+* stack is pinned to. Tests connect via this URL, so a reused stack must come back up on
+* the same port; `undefined` means no stack has ever been seeded here (a cold boot).
+*/
+function recordedPort() {
+	const path$1 = credentialsPath();
+	if (!existsSync(path$1)) return void 0;
+	try {
+		const { url } = JSON.parse(readFileSync(path$1, "utf-8"));
+		const port = new URL(url).port;
+		return port ? Number(port) : void 0;
+	} catch {
+		return;
+	}
+}
 
 //#endregion
-export { activateLocalPlugin, credentialsPath, ensurePlugin, ensurePlugins, findConfigDir, getTestCredentials, githubRelease, isSeeded, kizloRelease, resolvePluginSource };
+export { activateLocalPlugin, credentialsPath, ensurePlugin, ensurePlugins, findConfigDir, getTestCredentials, githubRelease, isSeeded, kizloRelease, recordedPort, resolvePluginSource };