kizlo 0.20.2 → 0.22.0

package/dist/category/index.js

@@ -18,7 +18,7 @@ const CATEGORY_PROCEDURES = {
 	}, async ({ input, context, errors }) => {
 		const identifier = parseIdentifier(input.params.identifier);
 		if (!identifier) throw errors.CATEGORY_NOT_FOUND();
-		const response = await context.wordpress.taxonomies.category.retrieve({ identifier: String(identifier.value) });
+		const response = await context.wordpress.kizlo.taxonomies.category.retrieve({ params: { identifier: String(identifier.value) } });
 		if (response.error) switch (response.error.code) {
 			case "invalid_taxonomy":
 			case "term_not_found":
@@ -41,7 +41,7 @@ const CATEGORY_PROCEDURES = {
 		output: schemaType(CategoryList),
 		errors: LIST_CATEGORY_ERROR_MAP
 	}, async ({ input, context, errors }) => {
-		const response = await context.wordpress.taxonomies.category.list({
+		const response = await context.wordpress.kizlo.taxonomies.category.list({ query: {
 			page: input.query?.page,
 			per_page: input.query?.perPage,
 			search: input.query?.search,
@@ -53,7 +53,7 @@ const CATEGORY_PROCEDURES = {
 			parent: input.query?.parent,
 			post: input.query?.post,
 			slug: normalizeArrayableValue(input.query?.slug)
-		});
+		} });
 		if (response.error) switch (response.error.code) {
 			case "rest_post_invalid_page_number": throw errors.CATEGORY_INVALID_PAGE();
 			case "rest_no_route": throw errors.CATEGORY_NOT_FOUND();

package/dist/category/schema.d.ts

@@ -4,7 +4,7 @@ import * as _kizlo_shared0 from "@kizlo/shared";
 import z from "zod/v4";
 
 //#region src/category/schema.d.ts
-type CategoryCustomFields = WP_CustomFields<"taxonomies.category">;
+type CategoryCustomFields = WP_CustomFields<"kizlo.taxonomies.category">;
 declare const CategoryCustomFieldsSchema: z.ZodType<CategoryCustomFields, CategoryCustomFields>;
 declare const Category: z.ZodObject<{
   id: z.ZodNumber;

package/dist/cli/commands/_setup.js

@@ -1,7 +1,7 @@
 import { DEFAULT_WORDPRESS_TAG, LOCAL_DIR_REL } from "../wp/constants.js";
 import { composeStop, createStack, dockerHint, dockerStatus } from "../wp/docker.js";
 import { DEFAULT_ENV_KEYS, availablePackageManagers, detectInvokingPackageManager, ensureGitignored, envGroups, envKeysPresent, mergeEnv, pickStackPort, writeFileIfAbsent } from "../utils.js";
-import { DEFAULT_DEV_DB_PORT, DEFAULT_DEV_PORT, resolveStackName, stackProject } from "../daemon/config.js";
+import { DEFAULT_DEV_DB_PORT, DEFAULT_DEV_PORT, DEFAULT_MCP_PORT, resolveStackName, stackProject } from "../daemon/config.js";
 import { promptFragment, resolvePromptDefault } from "../presets/template.js";
 import { createAdminAppPassword } from "../wp/bootstrap.js";
 import { bootstrapDev } from "../wp/dev.js";
@@ -324,6 +324,10 @@ function devConfigFor(cwd) {
 	return {
 		configDir: cwd,
 		project: stackProject(resolveStackName(cwd), "dev"),
+		mcp: {
+			port: DEFAULT_MCP_PORT,
+			portExplicit: false
+		},
 		port: DEFAULT_DEV_PORT,
 		portExplicit: false,
 		dbPort: DEFAULT_DEV_DB_PORT,

package/dist/cli/commands/dev.js

@@ -2,7 +2,7 @@ import { createStack, dockerHint, dockerStatus, stackStatus } from "../wp/docker
 import { findConfigDir } from "../wp/utils.js";
 import { log } from "../daemon/logger.js";
 import { DEFAULT_ENV_KEYS, ensureGitignored, envGroups, groupDefault, mergeEnv, pickStackPort, withSpinner } from "../utils.js";
-import { resolveDevConfig, usesLocalWordPress } from "../daemon/config.js";
+import { resolveDevConfig, resolveMcpConfig, usesLocalWordPress } from "../daemon/config.js";
 import { bootstrapDev } from "../wp/dev.js";
 import { reapOrphans, registerSession, removeProjectContainers, spawnWatchdog, unregisterSession } from "../wp/session.js";
 import { syncSiteSettings } from "../wp/settings.js";
@@ -10,6 +10,8 @@ import { devStack } from "../wp/stack.js";
 import { palette } from "../banner.js";
 import { watchReload } from "../daemon/reload.js";
 import { startWatcher } from "../daemon/watch.js";
+import { createMcpState } from "../mcp/state.js";
+import { resolveMcpPort, startMcp } from "../mcp/index.js";
 import { join } from "node:path";
 import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { defineCommand } from "citty";
@@ -42,14 +44,16 @@ function note(text) {
 * Print the connection summary as an aligned, Next.js-style block. Shows the wp-admin URL on
 * the loopback ("Local") and — when local WordPress is installed on a LAN address rather than
 * localhost — on the network, so it can be opened from other devices. On a fresh install, also
-* show the default wp-admin login.
+* show the default wp-admin login. The MCP row is the address to paste into a harness's own
+* configuration: nothing writes one, because each harness reads a different file.
 */
-function printSummary(info) {
+function printSummary(info, mcpUrl) {
 	const { cyan, dim, reset } = palette();
 	const { port, hostname } = new URL(info.url);
 	const rows = [["WP Local", `http://localhost:${port}/wp-admin`]];
 	if (hostname !== "localhost") rows.push(["WP Network", `${info.url}/wp-admin`]);
 	rows.push(["Database Connection", `127.0.0.1:${info.dbPort}`]);
+	if (mcpUrl) rows.push(["MCP", mcpUrl]);
 	const width = Math.max(...rows.map(([label]) => label.length)) + 1;
 	const lines = ["", ...rows.map(([label, value]) => `   ${dim}- ${`${label}:`.padEnd(width)}${reset} ${cyan}${value}${reset}`)];
 	if (info.adminPassword) lines.push("", `   ${dim}admin login:${reset} ${info.username} / ${info.adminPassword}`);
@@ -180,7 +184,7 @@ function stopping(reason) {
 * and the teardown work against. Shared by the first boot and every reload reboot, so a changed
 * `dev.port` in `kizlo.config.ts` is re-resolved the same way each time.
 */
-async function prepareStack(cfg) {
+async function prepareStack(cfg, mcpPort) {
 	await removeProjectContainers(cfg.project);
 	const port = await pickStackPort(cfg.port, {
 		fixed: cfg.portExplicit,
@@ -194,7 +198,8 @@ async function prepareStack(cfg) {
 	const ready = {
 		...cfg,
 		port,
-		dbPort
+		dbPort,
+		mcpPort: mcpPort ?? await resolveMcpPort(cfg.mcp)
 	};
 	createStack(devStack(ready));
 	if (port !== cfg.port) note(`Port ${cfg.port} is in use — serving on ${port} instead.`);
@@ -207,7 +212,7 @@ async function prepareStack(cfg) {
 * one-time Ctrl+C hint. `start` is when the boot began, so the timing spans the whole reboot including
 * the spinner. The `.env` writes here are why the caller pauses the reload watcher around a reboot.
 */
-async function report(cfg, creds, reloaded, start) {
+async function syncEnv(cfg, creds) {
 	if (creds.appPassword) {
 		const env = updateWpEnv(cfg, creds);
 		note("Updated .env with the new WordPress credentials");
@@ -224,7 +229,16 @@ async function report(cfg, creds, reloaded, start) {
 			if (!sync.ok) note(`Could not sync the site settings to WordPress (${sync.error}) — make sure the kizlo plugin is active, then set them from the Kizlo settings.`);
 		}
 	} else if (syncLocalUrl(cfg.configDir, creds.url)) note("Updated .env WordPress URL to the current network address — restart your app to pick it up");
-	printSummary(creds);
+}
+/**
+* Print the summary and the timed ready line, once everything it names is actually up. Split from
+* {@link syncEnv} because the two have opposite ordering needs: the `.env` writes have to land before
+* the watcher starts, since that is where it reads the connection from, while the summary has to wait
+* until after, so the MCP address it prints belongs to a server that exists. `mcpUrl` is absent when
+* MCP is not running, and the row is then left out rather than pointing at nothing.
+*/
+function printReady(creds, reloaded, start, mcpUrl) {
+	printSummary(creds, mcpUrl);
 	const { green, dim, bold, reset } = palette();
 	const ms = Date.now() - start;
 	const took = ms < 1e3 ? `${ms}ms` : `${(ms / 1e3).toFixed(1)}s`;
@@ -236,9 +250,14 @@ async function report(cfg, creds, reloaded, start) {
 * then report. The first-boot path only — reboots go through {@link rebootStack}, which also folds the
 * prepare step under the spinner.
 */
-async function bootAndReport(cfg) {
+async function bootAndSync(cfg) {
 	const start = Date.now();
-	await report(cfg, await withSpinner("Starting local WordPress", () => bootstrapDev(cfg)), false, start);
+	const creds = await withSpinner("Starting local WordPress", () => bootstrapDev(cfg));
+	await syncEnv(cfg, creds);
+	return {
+		creds,
+		start
+	};
 }
 /**
 * Reboot the whole stack in place after a config/env change: re-resolve the config, recreate the
@@ -247,17 +266,21 @@ async function bootAndReport(cfg) {
 * the first boot, so this never re-arms. Returns the freshly resolved config (ports may have moved) so
 * the caller can re-target its watchers.
 */
-async function rebootStack(cwd, label) {
+async function rebootStack(cwd, label, mcpPort) {
 	const start = Date.now();
 	const { ready, creds } = await withSpinner(label, async () => {
-		const ready$1 = await prepareStack(await resolveDevConfig(cwd));
+		const ready$1 = await prepareStack(await resolveDevConfig(cwd), mcpPort);
 		return {
 			ready: ready$1,
 			creds: await bootstrapDev(ready$1)
 		};
 	});
-	await report(ready, creds, true, start);
-	return ready;
+	await syncEnv(ready, creds);
+	return {
+		ready,
+		creds,
+		start
+	};
 }
 /**
 * Boot local WordPress and run in the foreground until exit — the path behind bare `kizlo dev`. Arms
@@ -273,20 +296,33 @@ async function startForeground(cfg) {
 	const cwd = process.cwd();
 	let ready = await prepareStack(cfg);
 	const shutdown = await armForegroundTeardown(ready);
-	await bootAndReport(ready);
+	const { creds, start } = await bootAndSync(ready);
 	const stack = {
 		status: () => stackStatus(ready.project),
 		onStopped: () => shutdown()
 	};
-	let stopContract = await startWatcher(ready.configDir, { stack });
+	const mcp = createMcpState();
+	const mcpPort = ready.mcpPort;
+	let stopContract = await startWatcher(ready.configDir, {
+		stack,
+		mcp
+	});
+	const mcpServer = stopContract && mcpPort !== void 0 ? await startMcp(mcp, mcpPort) : void 0;
+	if (!stopContract) log.info("Another `kizlo dev` is serving MCP for this project.");
+	printReady(creds, false, start, mcpServer?.url);
 	let reloading = false;
 	const reload = async (changed) => {
 		if (reloading) return;
 		reloading = true;
 		try {
 			stopContract?.();
-			ready = await rebootStack(cwd, `${changed} changed — restarting the session`);
-			stopContract = await startWatcher(ready.configDir, { stack });
+			const rebooted = await rebootStack(cwd, `${changed} changed — restarting the session`, mcpPort);
+			ready = rebooted.ready;
+			stopContract = await startWatcher(ready.configDir, {
+				stack,
+				mcp
+			});
+			printReady(rebooted.creds, true, rebooted.start, mcpServer?.url);
 		} catch (error) {
 			log.error("Failed to reload the dev session:", error);
 		} finally {
@@ -299,6 +335,7 @@ async function startForeground(cfg) {
 	process.on("exit", () => {
 		stopContract?.();
 		stopReload();
+		mcpServer?.stop();
 	});
 	setInterval(() => {}, 1 << 30);
 	await new Promise(() => {});
@@ -312,15 +349,20 @@ async function startForeground(cfg) {
 * persistent watcher keeps the process alive on its own.
 */
 async function watchOnly(cwd) {
-	let stop = await startWatcher(cwd);
-	if (!stop) return;
+	const mcp = createMcpState();
+	let stop = await startWatcher(cwd, { mcp });
+	if (!stop) {
+		log.info("Another `kizlo dev` is serving MCP for this project.");
+		return;
+	}
+	const mcpServer = await startMcp(mcp, await resolveMcpPort(await resolveMcpConfig(cwd)));
 	let reloading = false;
 	const reload = async () => {
 		if (reloading) return;
 		reloading = true;
 		try {
 			stop?.();
-			stop = await startWatcher(cwd);
+			stop = await startWatcher(cwd, { mcp });
 		} finally {
 			setTimeout(() => {
 				reloading = false;
@@ -331,6 +373,7 @@ async function watchOnly(cwd) {
 	const shutdown = () => {
 		stop?.();
 		stopReload();
+		mcpServer?.stop();
 	};
 	process.on("exit", shutdown);
 	for (const signal of [

package/dist/cli/daemon/config.js

@@ -50,6 +50,7 @@ const testStackSchema = z.object({
 	]).optional(),
 	command: z.string().optional()
 });
+const mcpSchema = z.object({ port: z.number().int().positive().optional() });
 const localSchema = z.union([z.boolean(), z.object({
 	enable: z.boolean().optional(),
 	name: z.string().optional(),
@@ -62,6 +63,7 @@ const configSchema = z.object({
 	dir: dirSchema.optional(),
 	alias: z.string().optional(),
 	local: localSchema.optional(),
+	mcp: mcpSchema.optional(),
 	wordpressClientDir: removedKey("`wordpressClientDir` has been removed. Use `dir: { introspection }` instead."),
 	name: removedKey("`name` is no longer a config root key. Move it under `local.name`."),
 	worktrees: removedKey("`worktrees` is no longer a config root key. Move it under `local.worktrees`."),
@@ -106,6 +108,16 @@ const CONFIG_FILES = [
 ];
 const DEFAULT_DEV_PORT = 8080;
 const DEFAULT_DEV_DB_PORT = 3307;
+/**
+* Port the MCP server binds on `127.0.0.1` when `mcp.port` is unset. It steps off a collision like the
+* stack ports do, so two projects need no configuration to run side by side. A harness config names a
+* port and cannot follow one that moves, which is what setting `mcp.port` is for.
+*
+* Deliberately clear of the stack ports' own scan ranges. Each default steps up to `PORT_SCAN_RANGE`
+* ports looking for a free one, so a default inside 8080-8179 could be handed to the dev stack and
+* then claimed again here, since the MCP probe runs before compose has published anything.
+*/
+const DEFAULT_MCP_PORT = 8300;
 const DEFAULT_TEST_PORT = 8889;
 /** The generated introspection artifact's filename, written under its resolved directory. */
 const INTROSPECTION_FILE = "introspection.ts";
@@ -290,6 +302,16 @@ async function resolveWatchCredentials(cwd) {
 	if (!wordPressConnectionComplete(env)) return void 0;
 	return resolveWordPressConnection(env).credentials;
 }
+function resolveMcp(fileConfig) {
+	return {
+		port: fileConfig?.mcp?.port ?? DEFAULT_MCP_PORT,
+		portExplicit: fileConfig?.mcp?.port !== void 0
+	};
+}
+/** Resolve `mcp` from `kizlo.config.*`, applying the defaults for a project that says nothing about it. */
+async function resolveMcpConfig(cwd) {
+	return resolveMcp(await loadConfigFile(findConfigDir(cwd)));
+}
 /**
 * Resolve the dev stack (`local.dev`) into concrete values for the `dev` command, applying defaults
 * (port 8080). The install folder is fixed at `.kizlo/local` (no longer a config choice), so there's
@@ -298,7 +320,8 @@ async function resolveWatchCredentials(cwd) {
 */
 async function resolveDevConfig(cwd) {
 	const configDir = findConfigDir(cwd);
-	const local = resolveLocal(await loadConfigFile(configDir));
+	const fileConfig = await loadConfigFile(configDir);
+	const local = resolveLocal(fileConfig);
 	const { dev } = local;
 	return {
 		configDir,
@@ -313,9 +336,10 @@ async function resolveDevConfig(cwd) {
 		wordpressTag: dev.version ?? DEFAULT_WORDPRESS_TAG,
 		fixtures: dev.fixtures ?? [],
 		wordpressPath: LOCAL_DIR_REL,
-		wordpressDir: path.resolve(configDir, LOCAL_DIR_REL)
+		wordpressDir: path.resolve(configDir, LOCAL_DIR_REL),
+		mcp: resolveMcp(fileConfig)
 	};
 }
 
 //#endregion
-export { CONFIG_FILES, DEFAULT_DEV_DB_PORT, DEFAULT_DEV_PORT, resolveConfig, resolveDevConfig, resolveStackName, resolveTestConfig, resolveWatchCredentials, stackProject, usesLocalWordPress };
+export { CONFIG_FILES, DEFAULT_DEV_DB_PORT, DEFAULT_DEV_PORT, DEFAULT_MCP_PORT, resolveConfig, resolveDevConfig, resolveMcpConfig, resolveStackName, resolveTestConfig, resolveWatchCredentials, stackProject, usesLocalWordPress };

package/dist/cli/daemon/generate.js

@@ -178,7 +178,7 @@ function reportPluginVersion(installed) {
 async function fetchDocument(cwd, options, etag) {
 	loadEnvFiles(cwd);
 	const result = await fetchIntrospection(options.credentials ?? resolveWordPressConnection(integrationEnv([node()])).credentials, {
-		etag: options.strict ? void 0 : etag,
+		etag: !options.strict && !options.seed ? etag : void 0,
 		fetch: options.fetch
 	});
 	reportPluginVersion(result.pluginVersion);
@@ -208,8 +208,14 @@ async function generateIntrospectionOnce(cfg, options = {}) {
 	if (options.skipIntrospection) return "skipped";
 	const file = path.resolve(cfg.cwd, cfg.introspectionPath);
 	const metaPath = path.resolve(cfg.cwd, cfg.introspectionMetaPath);
-	const result = await fetchDocument(cfg.cwd, options, readWordPressMeta(metaPath, file)?.etag);
+	const meta = readWordPressMeta(metaPath, file);
+	const result = await fetchDocument(cfg.cwd, options, meta?.etag);
 	if (!result?.document) return "unchanged";
+	options.onDocument?.(result.document);
+	if (options.seed && meta && result.document.hash === meta.hash) {
+		if (result.etag !== meta.etag) atomicWrite(metaPath, wordPressMeta(result.etag, result.document.hash));
+		return "unchanged";
+	}
 	const generated = generateWordPressModule(result.document);
 	await assertGeneratedClientCompiles(generated);
 	fs.mkdirSync(path.dirname(file), { recursive: true });

package/dist/cli/daemon/watch.js

@@ -103,8 +103,8 @@ function createWordPressRefresh(cfg, options, stack) {
 	};
 }
 /** Run {@link createWordPressRefresh} on a timer, skipping a tick while the previous one is still going. */
-function refreshWordPress(cfg, credentials, stack) {
-	const refresh = createWordPressRefresh(cfg, { credentials }, stack);
+function refreshWordPress(cfg, options, stack) {
+	const refresh = createWordPressRefresh(cfg, options, stack);
 	let refreshing = false;
 	const timer = setInterval(() => {
 		if (refreshing) return;
@@ -139,6 +139,14 @@ async function startWatcher(cwd, opts) {
 		const credentials = await resolveWatchCredentials(cwd);
 		const options = credentials ? { credentials } : { skipIntrospection: true };
 		if (!credentials) log.info("No WordPress connection configured; running the contract watcher only, introspection skipped.");
+		if (opts?.mcp) {
+			opts.mcp.credentials = credentials;
+			options.seed = true;
+			options.onDocument = (document) => {
+				if (opts.mcp) opts.mcp.document = document;
+				options.seed = false;
+			};
+		}
 		try {
 			const result = await generateOnce(cfg, options);
 			if (result.contract === "built") log.success("Contract generated");
@@ -148,7 +156,7 @@ async function startWatcher(cwd, opts) {
 			reportGenerationError("Failed to generate the Kizlo contract:", error);
 		}
 		const watcher = cfg.server ? await watch(cfg, cfg.server, options) : void 0;
-		const wordpressRefresh = credentials ? refreshWordPress(cfg, credentials, opts?.stack) : void 0;
+		const wordpressRefresh = credentials ? refreshWordPress(cfg, options, opts?.stack) : void 0;
 		let stopped = false;
 		handedOver = true;
 		return () => {

package/dist/cli/mcp/index.js

@@ -0,0 +1,46 @@
+import { log } from "../daemon/logger.js";
+import { pickStackPort } from "../utils.js";
+import { MCP_HOST, MCP_PATH, isAllowedOrigin, startMcpServer } from "./server.js";
+import { createMcpState } from "./state.js";
+
+//#region src/cli/mcp/index.ts
+/**
+* The port the server will bind, stepping off a collision unless the project pinned one.
+*
+* Resolved before the server starts so the dev summary can print the address alongside WordPress's.
+* A pinned port that is taken stops the command the way `dev.port` and `test.port` do: the developer
+* wrote that number, a harness config elsewhere names it, and quietly serving on a different one
+* would leave the harness connecting to nothing.
+*/
+async function resolveMcpPort(config) {
+	return pickStackPort(config.port, {
+		fixed: config.portExplicit,
+		host: MCP_HOST,
+		configKey: "mcp.port"
+	});
+}
+/**
+* Start the MCP server for a session that has a watcher, or say why it is not running.
+*
+* Called after the watcher starts and never inside its restart cycle. Two cases leave it off, and
+* neither is a failure of the session: another `kizlo dev` already holds the watcher lock and is
+* serving MCP itself (the caller skips this entirely), or there is no WordPress connection to expose,
+* where the contract watcher still has work to do and MCP has nothing to answer with.
+*/
+async function startMcp(state, port) {
+	if (!state.credentials) {
+		log.info("No WordPress connection configured; the MCP server is off for this session.");
+		return;
+	}
+	try {
+		const handle = await startMcpServer(state, { port });
+		log.success(`MCP server on ${handle.url}`);
+		return handle;
+	} catch (error) {
+		log.error("Failed to start the MCP server:", error);
+		return;
+	}
+}
+
+//#endregion
+export { resolveMcpPort, startMcp };

package/dist/cli/mcp/routes.js

@@ -0,0 +1,42 @@
+import { camel, endpointDefinition } from "../../wordpress/generate.js";
+
+//#region src/cli/mcp/routes.ts
+/**
+* Every operation in the document, keyed by route name.
+*
+* Built per call rather than cached: the watcher replaces the document whenever WordPress moves, and
+* a registry that outlived one would answer for routes that no longer exist while missing the ones
+* that just appeared. Walking a contract of a few hundred routes is far cheaper than getting that wrong.
+*/
+function routesOf(document) {
+	const routes = /* @__PURE__ */ new Map();
+	for (const [apiId, api] of Object.entries(document.apis)) {
+		const prefix = apiId.split(".").map(camel);
+		for (const [path, operations] of Object.entries(api.paths)) for (const [operationId, operation] of Object.entries(operations)) {
+			const name = [...prefix, camel(operationId)].join(".");
+			routes.set(name, {
+				name,
+				namespace: api.namespace,
+				method: operation.method,
+				path,
+				...operation.summary !== void 0 ? { summary: operation.summary } : {},
+				...operation.description !== void 0 ? { description: operation.description } : {},
+				...operation.deprecated !== void 0 ? { deprecated: operation.deprecated } : {},
+				operation,
+				definition: endpointDefinition({
+					namespace: api.namespace,
+					path,
+					operation
+				})
+			});
+		}
+	}
+	return routes;
+}
+/** Route names in the order a listing shows them, so two calls against one document agree. */
+function sortRoutes(routes) {
+	return [...routes].sort((left, right) => left.name.localeCompare(right.name));
+}
+
+//#endregion
+export { routesOf, sortRoutes };