kizlo 0.14.0 → 0.15.0

package/dist/cli/daemon/config.js

@@ -1,7 +1,8 @@
-import { LOCAL_DIR_REL } from "../wp/constants.js";
+import { DEFAULT_WORDPRESS_TAG, LOCAL_DIR_REL, WORDPRESS_META_REL } from "../wp/constants.js";
 import { credentialsPath, findConfigDir } from "../wp/utils.js";
 import { log } from "./logger.js";
 import { detectPackageManager } from "../utils.js";
+import { WORDPRESS_TAG_PATTERN } from "../wp/version.js";
 import { importIgnoringVirtualModules } from "./jiti.js";
 import z from "zod/v4";
 import path from "node:path";
@@ -9,20 +10,30 @@ import fs from "node:fs";
 
 //#region src/cli/daemon/config.ts
 const fixtureSchema = z.custom((value) => typeof value === "object" && value !== null && typeof value.name === "string", { message: "must be a fixture object with a string `name` (use defineFixture)" });
+/**
+* `dev.version` / `test.version`. Validated against Docker's tag grammar here rather than at boot,
+* so `"wordpress:7.1.0"`, which would resolve to `wordpress:wordpress:7.1.0`, is named as a config
+* mistake instead of surfacing as a pull failure seconds into starting a stack.
+*/
+const versionSchema = z.string().regex(WORDPRESS_TAG_PATTERN, "must be a WordPress image tag, like \"7.1.0\" or \"7.1.0-php8.3-apache\" (no \"wordpress:\" prefix)");
 /** Runtime shape of `kizlo.config.*` — mirrors {@link KizloGlobalConfig}. */
 const configSchema = z.object({
 	dir: z.string().optional(),
 	alias: z.string().optional(),
 	name: z.string().optional(),
+	worktrees: z.boolean().optional(),
+	wordpressClientDir: z.string().optional(),
 	dev: z.object({
 		local: z.boolean().optional(),
 		port: z.number().int().positive().optional(),
+		version: versionSchema.optional(),
 		dbPort: z.number().int().positive().optional(),
 		fixtures: z.array(fixtureSchema).optional()
 	}).optional(),
 	test: z.object({
 		local: z.boolean().optional(),
 		port: z.number().int().positive().optional(),
+		version: versionSchema.optional(),
 		fixtures: z.array(fixtureSchema).optional(),
 		packageManager: z.enum([
 			"npm",
@@ -80,29 +91,69 @@ async function resolveConfig(cwd, flags) {
 		serverEntry: path.join(serverDir, "index.ts"),
 		generatedDir,
 		contractPath: path.join(generatedDir, "contract.json"),
-		barrelPath: path.join(generatedDir, "index.ts")
+		barrelPath: path.join(generatedDir, "index.ts"),
+		wordpressPath: path.join(generatedDir, "wordpress.ts"),
+		wordpressMetaPath: WORDPRESS_META_REL
 	};
 }
 /**
+* The directory `wordpress.ts` is written to for a workspace with no Kizlo server, from `wordpressClientDir`
+* in `kizlo.config.*`. Resolved on its own rather than through {@link resolveConfig}, which describes a
+* server layout and returns nothing without `dir` — the two are independent.
+*/
+async function resolveWordPressClientDir(cwd) {
+	return (await loadConfigFile(cwd))?.wordpressClientDir;
+}
+/**
 * 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";
 }
+const HEAD_REF_PREFIX = "ref: refs/heads/";
+/**
+* The branch checked out at `dir`, read out of git's own files rather than by running git, so this
+* stays synchronous and works where git isn't on PATH. `.git` is a directory in a main checkout and
+* a file holding `gitdir: <path>` in a linked worktree, which is what makes each worktree report its
+* own branch. Returns undefined when there is no branch to name: no repository, an unreadable one, or
+* a detached `HEAD`, which holds a commit id instead of a ref.
+*/
+function currentBranch(dir) {
+	try {
+		const dotGit = path.join(dir, ".git");
+		let gitDir = dotGit;
+		if (fs.statSync(dotGit).isFile()) {
+			const pointer = fs.readFileSync(dotGit, "utf8").match(/^gitdir:\s*(.+)$/m);
+			if (!pointer?.[1]) return void 0;
+			gitDir = path.resolve(dir, pointer[1].trim());
+		}
+		const head = fs.readFileSync(path.join(gitDir, "HEAD"), "utf8").trim();
+		return head.startsWith(HEAD_REF_PREFIX) ? head.slice(16) : void 0;
+	} catch {
+		return;
+	}
+}
 /**
 * 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.
+*
+* With `worktrees` on, the checked-out branch is appended rather than replacing that name, so
+* sibling checkouts of one project separate while two unrelated projects sitting on the same branch
+* stay apart. Replacing it would collide those two, which is this option's own bug one level up.
 */
-function resolveStackName(configDir, configName) {
-	if (configName) return sanitizeProjectName(configName);
-	let pkgName;
+function resolveStackName(configDir, { name, worktrees } = {}) {
+	const base = name ? sanitizeProjectName(name) : sanitizeProjectName(packageName(configDir) ?? path.basename(configDir));
+	if (!worktrees) return base;
+	const branch = currentBranch(configDir);
+	return branch ? `${base}-${sanitizeProjectName(branch)}` : base;
+}
+function packageName(configDir) {
 	try {
-		pkgName = JSON.parse(fs.readFileSync(path.join(configDir, "package.json"), "utf8")).name;
+		return JSON.parse(fs.readFileSync(path.join(configDir, "package.json"), "utf8")).name;
 	} catch {
-		pkgName = void 0;
+		return;
 	}
-	return sanitizeProjectName(pkgName ?? path.basename(configDir));
 }
 /**
 * Compose project id for a stack: `kizlo-<name>-<kind>`. The leading `kizlo-` is what
@@ -124,10 +175,14 @@ async function resolveTestConfig(cwd) {
 	return {
 		configDir,
 		local: Boolean(test.local),
-		project: stackProject(resolveStackName(configDir, fileConfig?.name), "test"),
+		project: stackProject(resolveStackName(configDir, {
+			name: fileConfig?.name,
+			worktrees: fileConfig?.worktrees
+		}), "test"),
 		command: test.command,
 		port: test.port ?? DEFAULT_TEST_PORT,
-		portExplicit: test.port !== void 0,
+		portExplicit: test.port !== void 0 && !fileConfig?.worktrees,
+		wordpressTag: test.version ?? DEFAULT_WORDPRESS_TAG,
 		fixtures: test.fixtures ?? [],
 		credentialsPath: credentialsPath(cwd),
 		packageManager: test.packageManager ?? await detectPackageManager(configDir) ?? "npm"
@@ -156,11 +211,15 @@ async function resolveDevConfig(cwd) {
 	const dev = fileConfig?.dev ?? {};
 	return {
 		configDir,
-		project: stackProject(resolveStackName(configDir, fileConfig?.name), "dev"),
+		project: stackProject(resolveStackName(configDir, {
+			name: fileConfig?.name,
+			worktrees: fileConfig?.worktrees
+		}), "dev"),
 		port: dev.port ?? DEFAULT_DEV_PORT,
-		portExplicit: dev.port !== void 0,
+		portExplicit: dev.port !== void 0 && !fileConfig?.worktrees,
 		dbPort: dev.dbPort ?? DEFAULT_DEV_DB_PORT,
-		dbPortExplicit: dev.dbPort !== void 0,
+		dbPortExplicit: dev.dbPort !== void 0 && !fileConfig?.worktrees,
+		wordpressTag: dev.version ?? DEFAULT_WORDPRESS_TAG,
 		fixtures: dev.fixtures ?? [],
 		wordpressPath: LOCAL_DIR_REL,
 		wordpressDir: path.resolve(configDir, LOCAL_DIR_REL)
@@ -168,4 +227,4 @@ async function resolveDevConfig(cwd) {
 }
 
 //#endregion
-export { CONFIG_FILES, DEFAULT_DEV_DB_PORT, DEFAULT_DEV_PORT, resolveConfig, resolveDevConfig, resolveStackName, resolveTestConfig, stackProject, usesLocalWordPress };
+export { CONFIG_FILES, DEFAULT_DEV_DB_PORT, DEFAULT_DEV_PORT, resolveConfig, resolveDevConfig, resolveStackName, resolveTestConfig, resolveWordPressClientDir, stackProject, usesLocalWordPress };

package/dist/cli/daemon/generate.js

@@ -1,39 +1,246 @@
 import { generateContract } from "../../shared/contract.js";
+import { resolveWordPressConnection } from "../../kizlo.js";
+import { WORDPRESS_CLIENT_META_REL } from "../wp/constants.js";
+import { log } from "./logger.js";
 import { loadEnvFiles } from "../utils.js";
 import { importIgnoringVirtualModules } from "./jiti.js";
+import { IntrospectionVersionError } from "../../wordpress/introspection.js";
+import { fetchIntrospection } from "../../wordpress/fetch-introspection.js";
+import { generateWordPressModule } from "../../wordpress/generate.js";
+import { GeneratedClientTypeError, assertGeneratedClientCompiles } from "../../wordpress/typecheck.js";
+import { isPluginVersionSupported, pluginUpdateMessage } from "@kizlo/shared";
 import path from "node:path";
 import fs from "node:fs";
 
 //#region src/cli/daemon/generate.ts
-/** The generated contract barrel — also written as a stub by `kizlo init`. */
+/**
+* The generated barrel — also written as a stub by `kizlo init`. It re-exports `endpoints` rather
+* than pre-wrapping it: a server entry passes `wordpress: { endpoints }` itself, so the rest of the
+* WordPress options stay visible at the call site instead of hiding inside a generated object.
+*/
 const CONTRACT_BARREL = [
 	`import type { router } from ".."`,
 	`import contractJson from "./contract.json"`,
 	``,
 	`export const contract = contractJson as unknown as typeof router`,
+	`export { endpoints, type WordPressClient } from "./wordpress"`,
+	``
+].join("\n");
+/**
+* `wordpress.ts` before the first generation. WordPress is reachable but untyped until then, so a
+* freshly scaffolded project compiles — including kizlo's own procedures — before it has ever
+* connected. `kizlo dev` / `kizlo generate` replaces this with the real client. `any` rather than an
+* empty tree on purpose: every endpoint a procedure names has to resolve to something until the
+* real shapes arrive, which `WP_Client` preserves by passing `any` through.
+*/
+const WORDPRESS_STUB = [
+	`import type { WP_Client } from "kizlo"`,
+	``,
+	`export const endpoints = {} as any`,
+	``,
+	`export type WordPressClient = WP_Client<typeof endpoints>`,
+	``,
+	`declare module "kizlo" {`,
+	`\tinterface WordPressClientRegistry {`,
+	`\t\tendpoints: typeof endpoints`,
+	`\t}`,
+	`}`,
 	``
 ].join("\n");
 /** Write atomically: a reader never observes a half-written file. */
+let atomicWriteSequence = 0;
 function atomicWrite(file, data) {
-	const tmp = `${file}.${process.pid}.tmp`;
-	fs.writeFileSync(tmp, data);
-	fs.renameSync(tmp, file);
+	const tmp = `${file}.${process.pid}.${atomicWriteSequence++}.tmp`;
+	try {
+		fs.writeFileSync(tmp, data);
+		fs.renameSync(tmp, file);
+	} finally {
+		if (fs.existsSync(tmp)) fs.unlinkSync(tmp);
+	}
+}
+/** Enough of a generated file to hold its header: `// Generated by Kizlo` then `// Introspection <hash>`. */
+const INTROSPECTION_STAMP_BYTES = 256;
+/** The introspection hash a generated file was written from, read without loading the whole file. */
+function introspectionStamp(file) {
+	let handle;
+	try {
+		handle = fs.openSync(file, "r");
+		const buffer = Buffer.alloc(INTROSPECTION_STAMP_BYTES);
+		const bytes = fs.readSync(handle, buffer, 0, buffer.length, 0);
+		return /^\/\/ Introspection (\S+)$/m.exec(buffer.toString("utf8", 0, bytes))?.[1];
+	} catch {
+		return;
+	} finally {
+		if (handle !== void 0) fs.closeSync(handle);
+	}
+}
+/**
+* The ETag to revalidate with, or undefined to fetch afresh. An ETag is only worth sending when the
+* file it describes is still on disk and was written from the same introspection document it
+* names: a stub, a hand-edit, or output from an older generator all have to be replaced, and
+* answering 304 to any of them would leave the project compiling against something WordPress never served.
+*/
+function readWordPressMeta(metaPath, generatedFile) {
+	try {
+		const value = JSON.parse(fs.readFileSync(metaPath, "utf8"));
+		if (typeof value.etag !== "string" || typeof value.hash !== "string") return void 0;
+		if (introspectionStamp(generatedFile) !== value.hash) return void 0;
+		return value;
+	} catch {
+		return;
+	}
+}
+/** The fetch cache a generated file revalidates against, keyed to the document it was written from. */
+function wordPressMeta(etag, hash) {
+	return `${JSON.stringify({
+		etag,
+		hash
+	}, null, "	")}\n`;
+}
+/** Where a diagnostic landed: `schema_id > api_id > path > operation > pointer > keyword`, as sent. */
+function diagnosticLocation(diagnostic) {
+	return Object.values(diagnostic.data).filter(Boolean).join(" > ");
+}
+function formatDiagnostic(diagnostic) {
+	const location = diagnosticLocation(diagnostic);
+	return `${diagnostic.type}: ${location ? `${location}: ` : ""}${diagnostic.message}`;
+}
+/**
+* WordPress publishes everything that survived validation and names what it had to drop, so what a
+* partial contract is worth is the generator's call rather than the transport's. Taking it is the
+* default: a third-party plugin's broken declaration then costs its own routes and nothing else,
+* where refusing the document costs the project every route that still works, for a mistake in code
+* it does not own. Strict generation makes the opposite trade for CI, where a client silently short
+* of routes typechecks clean and ships the gap.
+*/
+var PartialContractError = class extends Error {
+	excluded;
+	constructor(excluded) {
+		super(`WordPress excluded ${excluded} ${excluded === 1 ? "contribution" : "contributions"} from the contract.`);
+		this.name = "PartialContractError";
+		this.excluded = excluded;
+	}
+};
+/**
+* Report a failed generation under `message`. A version mismatch and a refused partial contract are
+* diagnoses rather than faults: the message is the whole report, and the stack consola would print
+* beneath it buries the one line the user has to act on. Anything else is a fault and keeps its stack.
+*/
+function reportGenerationError(message, error) {
+	if (error instanceof IntrospectionVersionError || error instanceof PartialContractError) log.error(error.message);
+	else if (error instanceof GeneratedClientTypeError) log.error(error.message);
+	else log.error(message, error);
+}
+/**
+* Say what the document says about itself, then apply the policy. Warnings mean a declaration lost a
+* constraint and still types correctly, so they never gate anything; errors mean a contribution was
+* dropped and its routes and types are absent from what follows.
+*/
+function reportDiagnostics(document, strict) {
+	for (const diagnostic of document.diagnostics) if (diagnostic.type === "warning") log.warn(formatDiagnostic(diagnostic));
+	else log.error(formatDiagnostic(diagnostic));
+	const excluded = new Set(document.diagnostics.filter((diagnostic) => diagnostic.type === "error").map(diagnosticLocation));
+	if (!excluded.size) return;
+	if (strict) throw new PartialContractError(excluded.size);
+	log.warn(`Generating without the ${excluded.size} excluded ${excluded.size === 1 ? "contribution" : "contributions"} above. Their routes and types are missing from the client; \`kizlo generate --strict\` refuses the contract instead.`);
+}
+/**
+* Plugin versions already named as outdated. `kizlo dev` refetches every few seconds, and the answer
+* cannot change until the plugin does, so the warning is worth one line per version rather than one
+* per poll. An updated plugin that is still too old is a version this has not seen, and says so again.
+*/
+const reportedPluginVersions = /* @__PURE__ */ new Set();
+/**
+* Name a plugin too old for this package at generation, where it is still actionable, rather than
+* leaving it to the runtime's first request. A warning either way, strict included: strict decides
+* what to do about routes WordPress excluded, and an outdated plugin excludes nothing by itself.
+*/
+function reportPluginVersion(installed) {
+	if (isPluginVersionSupported(installed)) return;
+	const key = installed ?? "";
+	if (reportedPluginVersions.has(key)) return;
+	reportedPluginVersions.add(key);
+	log.warn(pluginUpdateMessage(installed));
+}
+/** Fetch `/introspect`, reporting its diagnostics in the CLI's voice. Returns undefined on a 304. */
+async function fetchDocument(cwd, options, etag) {
+	loadEnvFiles(cwd);
+	const result = await fetchIntrospection(options.credentials ?? resolveWordPressConnection(void 0).credentials, {
+		etag: options.strict ? void 0 : etag,
+		fetch: options.fetch
+	});
+	reportPluginVersion(result.pluginVersion);
+	if (result.status === "not-modified") return void 0;
+	if (!result.document) throw new Error("WordPress introspection returned no document.");
+	reportDiagnostics(result.document, options.strict === true);
+	return result;
+}
+/**
+* Produce the WordPress client without writing it or its ETag cache. Health checks use this to ask
+* the same generator as `kizlo generate` what should be on disk, while leaving a contributor's
+* checkout untouched. Callers choose strictness just as generation does.
+*/
+async function generateWordPressSource(cwd, options = {}) {
+	const result = await fetchDocument(cwd, options);
+	if (!result?.document) throw new Error("WordPress introspection returned no document.");
+	const generated = generateWordPressModule(result.document);
+	await assertGeneratedClientCompiles(generated);
+	return generated.source;
+}
+async function generateWordPressOnce(cfg, options = {}) {
+	const etag = readWordPressMeta(path.resolve(cfg.cwd, cfg.wordpressMetaPath), path.resolve(cfg.cwd, cfg.wordpressPath))?.etag;
+	const result = await fetchDocument(cfg.cwd, options, etag);
+	if (!result?.document) return "unchanged";
+	const generated = generateWordPressModule(result.document);
+	await assertGeneratedClientCompiles(generated);
+	writeGeneratedWordPress(cfg, generated.source, wordPressMeta(result.etag, result.document.hash));
+	return "generated";
+}
+/**
+* Write `<dir>/wordpress.ts` once for a whole workspace. Every package that ships procedures compiles
+* against the same file, so there is one description of WordPress in the repo rather than one per
+* package drifting apart. One shape too: a package that only wants the types today still gets the
+* class, so reaching for the runtime later needs no regeneration.
+*/
+async function generateWorkspaceClientOnce(cwd, dir, options = {}) {
+	const file = path.resolve(cwd, dir, "wordpress.ts");
+	const metaPath = path.resolve(cwd, WORDPRESS_CLIENT_META_REL);
+	const result = await fetchDocument(cwd, options, readWordPressMeta(metaPath, file)?.etag);
+	if (!result?.document) return "unchanged";
+	const generated = generateWordPressModule(result.document);
+	await assertGeneratedClientCompiles(generated);
+	const contents = generated.source;
+	fs.mkdirSync(path.dirname(metaPath), { recursive: true });
+	atomicWrite(metaPath, wordPressMeta(result.etag, result.document.hash));
+	if (fs.existsSync(file) && fs.readFileSync(file, "utf8") === contents) return "unchanged";
+	fs.mkdirSync(path.dirname(file), { recursive: true });
+	atomicWrite(file, contents);
+	return "generated";
+}
+function writeGeneratedWordPress(cfg, client, meta) {
+	const metaPath = path.resolve(cfg.cwd, cfg.wordpressMetaPath);
+	fs.mkdirSync(path.resolve(cfg.cwd, cfg.generatedDir), { recursive: true });
+	fs.mkdirSync(path.dirname(metaPath), { recursive: true });
+	atomicWrite(path.resolve(cfg.cwd, cfg.wordpressPath), client);
+	atomicWrite(metaPath, meta);
 }
 /**
 * Loads the Kizlo server, builds its contract, and writes `contract.json` and
 * the generated barrel. Returns false when the entry has no Kizlo server.
 */
-async function generateOnce(cfg) {
+async function generateOnce(cfg, options = {}) {
 	loadEnvFiles(cfg.cwd);
 	const entry = path.resolve(cfg.cwd, cfg.serverEntry);
 	const { router } = await importIgnoringVirtualModules(cfg.cwd, entry);
 	if (!router) return false;
 	const contract = JSON.stringify(await generateContract(router));
+	const wordpress = await generateWordPressOnce(cfg, options);
 	fs.mkdirSync(path.resolve(cfg.cwd, cfg.generatedDir), { recursive: true });
 	atomicWrite(path.resolve(cfg.cwd, cfg.contractPath), contract);
 	atomicWrite(path.resolve(cfg.cwd, cfg.barrelPath), CONTRACT_BARREL);
+	if (wordpress === "generated") log.success("WordPress client generated");
 	return true;
 }
 
 //#endregion
-export { CONTRACT_BARREL, generateOnce };
+export { CONTRACT_BARREL, PartialContractError, WORDPRESS_STUB, generateOnce, generateWordPressOnce, generateWordPressSource, generateWorkspaceClientOnce, reportGenerationError };

package/dist/cli/daemon/lock.js

@@ -1,3 +1,4 @@
+import { currentProcessOwner, ownerAlive } from "../process-owner.js";
 import path from "node:path";
 import fs from "node:fs";
 
@@ -5,21 +6,42 @@ import fs from "node:fs";
 function lockPath(cwd) {
 	return path.join(cwd, "node_modules/.cache/kizlo/dev.lock");
 }
-/** True when a live daemon already owns the lock. Stale locks are ignored. */
-function isLocked(file) {
+/** True when a live daemon still owns the process identity recorded by the lock. */
+async function isLocked(file) {
 	if (!fs.existsSync(file)) return false;
-	const pid = Number(fs.readFileSync(file, "utf8").trim());
-	if (!pid) return false;
+	const contents = fs.readFileSync(file, "utf8").trim();
+	let owner;
 	try {
-		process.kill(pid, 0);
-		return true;
+		owner = contents.startsWith("{") ? JSON.parse(contents) : { pid: Number(contents) };
 	} catch {
 		return false;
 	}
+	return ownerAlive(owner);
+}
+/** Claim the file for this process, or report that it was already there. */
+function claim(file, owner) {
+	try {
+		fs.writeFileSync(file, JSON.stringify(owner), { flag: "wx" });
+		return true;
+	} catch (error) {
+		if (error.code !== "EEXIST") throw error;
+		return false;
+	}
 }
-function acquire(file) {
+/**
+* Take the lock for this process, answering false when a live daemon already holds it. The file is
+* created with `wx`, so two `kizlo dev` starting together cannot both come away believing they won.
+* A lock whose owner has died or whose PID belongs to another process is removed and taken over.
+* Losing the second claim means another process reached the same stale lock first, so this one
+* stands down rather than trying again.
+*/
+async function acquire(file) {
 	fs.mkdirSync(path.dirname(file), { recursive: true });
-	fs.writeFileSync(file, String(process.pid));
+	const owner = await currentProcessOwner();
+	if (claim(file, owner)) return true;
+	if (await isLocked(file)) return false;
+	fs.rmSync(file, { force: true });
+	return claim(file, owner);
 }
 function release(file) {
 	try {
@@ -28,4 +50,4 @@ function release(file) {
 }
 
 //#endregion
-export { acquire, isLocked, lockPath, release };
+export { acquire, lockPath, release };

package/dist/cli/daemon/watch.js

@@ -1,7 +1,10 @@
+import { resolveWordPressConnection } from "../../kizlo.js";
 import { log } from "./logger.js";
-import { resolveConfig } from "./config.js";
-import { generateOnce } from "./generate.js";
-import { acquire, isLocked, lockPath, release } from "./lock.js";
+import { loadEnvFiles } from "../utils.js";
+import { resolveConfig, resolveWordPressClientDir } from "./config.js";
+import { IntrospectionFetchError } from "../../wordpress/fetch-introspection.js";
+import { generateOnce, generateWordPressOnce, generateWorkspaceClientOnce, reportGenerationError } from "./generate.js";
+import { acquire, lockPath, release } from "./lock.js";
 import path from "node:path";
 import { FSWatcher } from "chokidar";
 
@@ -13,27 +16,117 @@ function debounce(fn, delay) {
 		timer = setTimeout(() => void fn(...args), delay);
 	});
 }
-async function regenerate(cfg) {
+async function regenerate(cfg, credentials) {
 	try {
-		if (await generateOnce(cfg)) log.success("Contract updated");
+		if (await generateOnce(cfg, { credentials })) log.success("Contract updated");
 		else log.warn(`No Kizlo server found in ${cfg.serverEntry}`);
 	} catch (error) {
-		log.error("Failed to update the Kizlo contract:", error);
+		reportGenerationError("Failed to update the Kizlo contract:", error);
 	}
 }
 /** Watches the server directory and regenerates the contract on change. */
-async function watch(cfg) {
+async function watch(cfg, credentials) {
 	const watcher = new FSWatcher({
 		persistent: true,
 		ignoreInitial: true,
 		ignored: path.resolve(cfg.cwd, cfg.generatedDir)
 	});
-	const onChange = debounce(() => regenerate(cfg), 300);
+	const onChange = debounce(() => regenerate(cfg, credentials), 300);
 	watcher.add(path.resolve(cfg.cwd, cfg.serverDir));
 	watcher.on("all", () => void onChange());
 	return watcher;
 }
 /**
+* Report one generation's pass under its own name. The poll refreshes two, and one message for both sent
+* a client-only workspace looking for a WordPress service its project does not have.
+*
+* Each reporter carries the last failure it reported, because most of what can fail here cannot clear
+* without the user acting — WordPress down, credentials wrong, a document that will not parse, an
+* introspection version this package does not speak — and repeating the same line every few seconds says
+* nothing the first one did not. A failure that reads differently is a different answer and is reported.
+* The state is per reporter rather than per process, so restarting the watcher reports afresh, and one
+* generation failing never silences the other.
+*/
+function reportGeneration(subject, stack) {
+	let reported;
+	return async (run) => {
+		try {
+			if (await run() === "generated") log.success(`WordPress ${subject} updated`);
+			stack?.answered();
+			if (reported !== void 0) {
+				reported = void 0;
+				log.success(`Updating the WordPress ${subject} again`);
+			}
+		} catch (error) {
+			if (error instanceof IntrospectionFetchError && error.unreachable && await stack?.ended()) return;
+			const message = error instanceof Error ? error.message : String(error);
+			if (message === reported) return;
+			reported = message;
+			reportGenerationError(`Failed to update the WordPress ${subject}:`, error);
+		}
+	};
+}
+/**
+* How often the guard may ask Docker while the poll keeps failing. The poll retries every 3 seconds,
+* and asking on every failing pass would spawn a subprocess that often for as long as WordPress is
+* unreachable — which, when the stack is up and WordPress is merely broken, is indefinitely. A stack
+* does not stop and restart between two passes, so the slower clock costs at most one interval before
+* the session ends and saves the other four probes.
+*/
+const STACK_PROBE_INTERVAL_MS = 15e3;
+function endOnStoppedStack(stack, now = Date.now) {
+	let done = false;
+	let probedAt;
+	return {
+		answered: () => {
+			probedAt = void 0;
+		},
+		ended: async () => {
+			if (done) return true;
+			const at = now();
+			if (probedAt !== void 0 && at - probedAt < STACK_PROBE_INTERVAL_MS) return false;
+			probedAt = at;
+			if (await stack.status() !== "stopped") return false;
+			done = true;
+			log.error("Local WordPress is no longer running. Ending the dev session.");
+			stack.onStopped();
+			return true;
+		}
+	};
+}
+/**
+* One pass of the WordPress poll. `cfg` covers an app's client next to its contract; `wordpressClientDir`
+* covers a workspace that has only the client. A project has one or the other, but both are refreshed
+* together so the plugin's PHP changing is picked up either way. Each is refreshed independently, so a
+* service that cannot generate does not cost the pass its client.
+*
+* Both reporters share one stack guard, so a stopped stack ends the session once rather than once per
+* generation the pass refreshes.
+*/
+function createWordPressRefresh(cwd, cfg, wordpressClientDir, options, stack) {
+	const guard = stack ? endOnStoppedStack(stack) : void 0;
+	const service = reportGeneration("service", guard);
+	const client = reportGeneration("client", guard);
+	return async () => {
+		if (cfg) await service(() => generateWordPressOnce(cfg, options));
+		if (wordpressClientDir) await client(() => generateWorkspaceClientOnce(cwd, wordpressClientDir, options));
+	};
+}
+/** Run {@link createWordPressRefresh} on a timer, skipping a tick while the previous one is still going. */
+function refreshWordPress(cwd, cfg, wordpressClientDir, credentials, stack) {
+	const refresh = createWordPressRefresh(cwd, cfg, wordpressClientDir, { credentials }, stack);
+	let refreshing = false;
+	const timer = setInterval(() => {
+		if (refreshing) return;
+		refreshing = true;
+		refresh().finally(() => {
+			refreshing = false;
+		});
+	}, 3e3);
+	timer.unref();
+	return timer;
+}
+/**
 * 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 framework dev
@@ -43,30 +136,45 @@ async function watch(cfg) {
 */
 async function startWatcher(cwd, opts) {
 	const lock = lockPath(cwd);
-	if (isLocked(lock)) {
+	if (!await acquire(lock)) {
 		log.info("Watcher already running — skipping the contract watcher.");
 		return;
 	}
-	const cfg = await resolveConfig(cwd, { dir: opts?.dir });
-	if (!cfg) {
-		log.info("skipping the contract generation.");
-		return;
-	}
-	acquire(lock);
+	let handedOver = false;
 	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 cfg = await resolveConfig(cwd, { dir: opts?.dir });
+		const wordpressClientDir = await resolveWordPressClientDir(cwd);
+		if (!cfg && !wordpressClientDir) {
+			log.info("skipping the contract generation.");
+			return;
+		}
+		loadEnvFiles(cwd);
+		const { credentials } = resolveWordPressConnection(void 0);
+		if (wordpressClientDir) try {
+			if (await generateWorkspaceClientOnce(cwd, wordpressClientDir, { credentials }) === "generated") log.success("WordPress client generated");
+		} catch (error) {
+			reportGenerationError("Failed to generate the WordPress client:", error);
+		}
+		if (cfg) try {
+			if (await generateOnce(cfg, { credentials })) log.success("Contract generated");
+			else log.warn(`No Kizlo server found in ${cfg.serverEntry}`);
+		} catch (error) {
+			reportGenerationError("Failed to generate the Kizlo contract:", error);
+		}
+		const watcher = cfg ? await watch(cfg, credentials) : void 0;
+		const wordpressRefresh = refreshWordPress(cwd, cfg, wordpressClientDir, credentials, opts?.stack);
+		let stopped = false;
+		handedOver = true;
+		return () => {
+			if (stopped) return;
+			stopped = true;
+			release(lock);
+			clearInterval(wordpressRefresh);
+			watcher?.close();
+		};
+	} finally {
+		if (!handedOver) release(lock);
 	}
-	const watcher = await watch(cfg);
-	let stopped = false;
-	return () => {
-		if (stopped) return;
-		stopped = true;
-		release(lock);
-		watcher.close();
-	};
 }
 
 //#endregion