kizlo 0.14.1 → 0.15.1

package/dist/category/error.js

@@ -5,10 +5,16 @@ const GET_CATEGORY_ERROR_MAP = defineErrorMap({ CATEGORY_NOT_FOUND: {
 	status: 404,
 	message: "Category not found"
 } });
-const LIST_CATEGORY_ERROR_MAP = defineErrorMap({ CATEGORY_INVALID_PAGE: {
-	status: 400,
-	message: "The requested page does not exist."
-} });
+const LIST_CATEGORY_ERROR_MAP = defineErrorMap({
+	CATEGORY_INVALID_PAGE: {
+		status: 400,
+		message: "The requested page does not exist."
+	},
+	CATEGORY_NOT_FOUND: {
+		status: 404,
+		message: "Categories are not available."
+	}
+});
 
 //#endregion
 export { GET_CATEGORY_ERROR_MAP, LIST_CATEGORY_ERROR_MAP };

package/dist/category/index.js

@@ -1,10 +1,10 @@
 import { createProcedure } from "../shared/procedure.js";
 import { parseIdentifier } from "../shared/identifier.js";
 import { deserializeListMetadata } from "../shared/serialize.js";
-import { getTaxonomyService } from "../taxonomy/service.js";
 import { GET_CATEGORY_ERROR_MAP, LIST_CATEGORY_ERROR_MAP } from "./error.js";
 import { Category, CategoryList, ListCategoryInput, RetrieveCategoryInput } from "./schema.js";
 import { deserializeCategory } from "./utils.js";
+import { normalizeArrayableValue } from "@kizlo/shared";
 
 //#region src/category/index.ts
 const CATEGORY_ROUTER_MAP = {
@@ -16,14 +16,14 @@ const CATEGORY_ROUTER_MAP = {
 		output: Category,
 		errors: GET_CATEGORY_ERROR_MAP
 	}, async ({ input, context, errors }) => {
-		const taxonomy = getTaxonomyService("category", context.wordpress);
 		const identifier = parseIdentifier(input.params.identifier);
 		if (!identifier) throw errors.CATEGORY_NOT_FOUND();
-		const response = await taxonomy.get(identifier);
+		const response = await context.wordpress.taxonomies.category.retrieve({ identifier: String(identifier.value) });
 		if (response.error) switch (response.error.code) {
 			case "invalid_taxonomy":
 			case "term_not_found":
-			case "rest_term_invalid": throw errors.CATEGORY_NOT_FOUND();
+			case "rest_term_invalid":
+			case "rest_no_route": throw errors.CATEGORY_NOT_FOUND();
 			default:
 				context.logger.error("Get category unhandled error", response.error, {
 					identifier,
@@ -41,22 +41,22 @@ const CATEGORY_ROUTER_MAP = {
 		output: CategoryList,
 		errors: LIST_CATEGORY_ERROR_MAP
 	}, async ({ input, context, errors }) => {
-		const response = await getTaxonomyService("category", context.wordpress).list({
-			context: "edit",
+		const response = await context.wordpress.taxonomies.category.list({
 			page: input.query?.page,
 			per_page: input.query?.perPage,
 			search: input.query?.search,
-			exclude: input.query?.exclude,
-			include: input.query?.include,
+			exclude: normalizeArrayableValue(input.query?.exclude),
+			include: normalizeArrayableValue(input.query?.include),
 			order: input.query?.order,
 			orderby: input.query?.orderBy,
 			hide_empty: input.query?.hideEmpty,
 			parent: input.query?.parent,
 			post: input.query?.post,
-			slug: input.query?.slug
+			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();
 			default:
 				context.logger.error("List categories unhandled error", response.error, { code: response.error.code });
 				throw errors.INTERNAL_SERVER_ERROR();

package/dist/category/schema.js

@@ -1,10 +1,19 @@
 import { IdentifierInput, ListMetadata, ListOrder } from "../shared/schema.js";
-import { WP_CATEGORY_ORDER_BYS } from "../wordpress/category/types.js";
 import { Seo } from "../seo/schema.js";
 import { BooleanLike, Metadata, NumberLike, arrayable, lenient } from "@kizlo/shared";
 import z from "zod/v4";
 
 //#region src/category/schema.ts
+const WP_CATEGORY_ORDER_BYS = [
+	"id",
+	"include",
+	"name",
+	"slug",
+	"include_slugs",
+	"term_group",
+	"description",
+	"count"
+];
 const Category = z.object({
 	id: z.number(),
 	name: z.string(),

package/dist/category/utils.js

@@ -7,12 +7,12 @@ function deserializeCategory(data) {
 		id: data.id,
 		name: data.name,
 		slug: data.slug,
-		url: data.kizlo.url ?? null,
+		url: data.kizlo.url,
 		description: data.description.length > 0 ? data.description : null,
 		parent: data.parent > 0 ? data.parent : null,
 		postCount: data.count,
-		seo: data.kizlo.seo ? deserializeSeo(data.kizlo.seo) : null,
-		meta: stringifiedMetaRecord(data.meta ?? {})
+		seo: "seo" in data.kizlo ? deserializeSeo(data.kizlo.seo) : null,
+		meta: stringifiedMetaRecord(data.meta)
 	};
 }
 

package/dist/cli/commands/_setup.js

@@ -1,8 +1,8 @@
-import { LOCAL_DIR_REL } from "../wp/constants.js";
+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 { promptFragment, resolvePromptDefault } from "../presets/template.js";
 import { DEFAULT_DEV_DB_PORT, DEFAULT_DEV_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";
 import { removeProjectContainers } from "../wp/session.js";
@@ -129,7 +129,8 @@ async function selectPackageManager(message) {
 }
 /** The choices summary shows a prompt under a short label — the title-cased token (`linter` → `Linter`). */
 function promptLabel(token) {
-	return token.charAt(0).toUpperCase() + token.slice(1);
+	const spaced = token.replace(/([a-z0-9])([A-Z])/g, "$1 $2");
+	return spaced.charAt(0).toUpperCase() + spaced.slice(1);
 }
 /** What a resolved prompt answer reads as in the choices summary: the option label, `Yes`/`No`, or the text. */
 function promptDisplay(prompt, answer) {
@@ -327,6 +328,7 @@ function devConfigFor(cwd) {
 		portExplicit: false,
 		dbPort: DEFAULT_DEV_DB_PORT,
 		dbPortExplicit: false,
+		wordpressTag: DEFAULT_WORDPRESS_TAG,
 		fixtures: [],
 		wordpressPath: LOCAL_DIR_REL,
 		wordpressDir: path.resolve(cwd, LOCAL_DIR_REL)

package/dist/cli/commands/_test-wordpress.js

@@ -0,0 +1,27 @@
+import { resolveTestConfig } from "../daemon/config.js";
+import fs from "node:fs";
+
+//#region src/cli/commands/_test-wordpress.ts
+/** Turn the test harness artifact into the credentials accepted by the introspection transport. */
+function wordPressCredentialsFromTestArtifact(artifact, project) {
+	if (artifact.project && artifact.project !== project) throw new Error("The saved test credentials belong to another WordPress stack. Run `kizlo test` first.");
+	return {
+		url: artifact.url,
+		username: artifact.users.admin.username,
+		password: artifact.users.admin.applicationPassword
+	};
+}
+/** Read credentials written by `kizlo test`, ensuring they belong to this branch's configured stack. */
+async function testWordPressCredentials(cwd) {
+	const config = await resolveTestConfig(cwd);
+	let artifact;
+	try {
+		artifact = JSON.parse(fs.readFileSync(config.credentialsPath, "utf8"));
+	} catch {
+		throw new Error("No test WordPress credentials found. Run `kizlo test` first.");
+	}
+	return wordPressCredentialsFromTestArtifact(artifact, config.project);
+}
+
+//#endregion
+export { testWordPressCredentials };

package/dist/cli/commands/_wiring.js

@@ -1,7 +1,7 @@
 import { aliasWithSlash, resolveModuleImport, writeFileIfAbsent } from "../utils.js";
+import { CONTRACT_BARREL, WORDPRESS_STUB } from "../daemon/generate.js";
 import { resolvePatch } from "../presets/template.js";
 import { orCancel } from "./_setup.js";
-import { CONTRACT_BARREL } from "../daemon/generate.js";
 import { applyPatchToSource, patchChanged, renderPatchCode, resolvePatchTargetPath } from "../presets/patch.js";
 import path from "node:path";
 import fs from "node:fs";
@@ -77,6 +77,7 @@ function writeGeneratedContract(cwd, serverDirRel) {
 	const generatedDirRel = path.join(serverDirRel, "generated");
 	writeFileIfAbsent(path.join(cwd, generatedDirRel, "contract.json"), "{}\n");
 	writeFileIfAbsent(path.join(cwd, generatedDirRel, "index.ts"), CONTRACT_BARREL);
+	writeFileIfAbsent(path.join(cwd, generatedDirRel, "wordpress.ts"), WORDPRESS_STUB);
 }
 /**
 * Apply every patch a template declares, merging Kizlo wiring into files the project already owns

package/dist/cli/commands/check.js

@@ -0,0 +1,99 @@
+import { log } from "../daemon/logger.js";
+import { resolveConfig, resolveWordPressClientDir } from "../daemon/config.js";
+import { generateWordPressSource, reportGenerationError } from "../daemon/generate.js";
+import { testWordPressCredentials } from "./_test-wordpress.js";
+import path from "node:path";
+import fs from "node:fs";
+import { defineCommand } from "citty";
+import { createTwoFilesPatch } from "diff";
+
+//#region src/cli/commands/check.ts
+/** Compare generated output with every configured copy without changing the files. */
+function findGeneratedFileMismatches(files, expected) {
+	const mismatches = [];
+	for (const file of files) {
+		const actual = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+		if (actual !== expected) mismatches.push({
+			file,
+			actual,
+			expected
+		});
+	}
+	return mismatches;
+}
+/** A standard unified diff, labelled so CI says which side is committed and which is current. */
+function formatGeneratedFileDiff(cwd, mismatch) {
+	const file = path.relative(cwd, mismatch.file) || path.basename(mismatch.file);
+	return createTwoFilesPatch(file, file, mismatch.actual, mismatch.expected, "committed", "generated", { context: 3 });
+}
+/** Every WordPress client the project configuration says it owns, with duplicates collapsed. */
+async function wordPressClientFiles(cwd, dir) {
+	const files = /* @__PURE__ */ new Set();
+	const workspaceDir = await resolveWordPressClientDir(cwd);
+	if (workspaceDir) files.add(path.resolve(cwd, workspaceDir, "wordpress.ts"));
+	const config = await resolveConfig(cwd, { dir });
+	if (config) files.add(path.resolve(cwd, config.wordpressPath));
+	return [...files];
+}
+const check = defineCommand({
+	meta: {
+		name: "check",
+		description: "Check the Kizlo project without changing files"
+	},
+	args: {
+		dir: {
+			type: "string",
+			description: "Override the Kizlo directory (defaults to kizlo.config.ts)"
+		},
+		test: {
+			type: "boolean",
+			description: "Check against WordPress left running by kizlo test"
+		}
+	},
+	async run({ args }) {
+		const cwd = process.cwd();
+		const files = await wordPressClientFiles(cwd, args.dir);
+		if (files.length === 0) {
+			log.info("No generated WordPress client configured, nothing to check.");
+			return;
+		}
+		let credentials;
+		if (args.test) try {
+			credentials = await testWordPressCredentials(cwd);
+		} catch (error) {
+			log.error(error instanceof Error ? error.message : String(error));
+			process.exitCode = 1;
+			return;
+		}
+		let expected;
+		try {
+			expected = await generateWordPressSource(cwd, {
+				credentials,
+				strict: true
+			});
+		} catch (error) {
+			reportGenerationError("Failed to check the generated WordPress client:", error);
+			process.exitCode = 1;
+			return;
+		}
+		const mismatches = findGeneratedFileMismatches(files, expected);
+		if (mismatches.length === 0) {
+			log.success(`${files.length === 1 ? "WordPress client is" : "WordPress clients are"} current`);
+			return;
+		}
+		for (const mismatch of mismatches) {
+			log.error(`${path.relative(cwd, mismatch.file)} is stale`);
+			process.stderr.write(`${formatGeneratedFileDiff(cwd, mismatch)}\n`);
+		}
+		const command = [
+			"kizlo generate",
+			args.test ? "--test" : "",
+			args.dir ? `--dir ${args.dir}` : ""
+		].filter(Boolean).join(" ");
+		log.info(`Run \`${command}\` and commit the updated client.`);
+		process.exitCode = 1;
+	}
+});
+
+//#endregion
+export { check };

package/dist/cli/commands/create.js

@@ -1,4 +1,4 @@
-import { approveBuildsCommand, cleanupWorkspaceArtifacts, detectInvokingPackageManager, detectPackageManager, ensureGitignored, findWorkspaceRoot, initGitRepository, installArgs, isCommandAvailable, isGitRepository, isWorkspaceMember, runCommandCapturedAsync, tokenizeCommand } from "../utils.js";
+import { aliasWithSlash, approveBuildsCommand, cleanupWorkspaceArtifacts, detectInvokingPackageManager, detectPackageManager, effectiveAlias, ensureGitignored, findWorkspaceRoot, initGitRepository, installArgs, isCommandAvailable, isGitRepository, isWorkspaceMember, runCommandCapturedAsync, tokenizeCommand } from "../utils.js";
 import { fetchRegistry, listTemplates, resolveRegistry } from "../presets/source.js";
 import { adaptFile, changesFor, fileEntries, minCliError, patchEntries, readManifest, resolveDependencies } from "../presets/template.js";
 import { collectConnectionFromEnv, collectConnectionInteractively, collectTemplatePrompts, nextStepsLines, orCancel, pickAppPort, provisionLocalWordPress, readEnvExample, resolveEnvKeys, selectPackageManager, syncRemote, validate, withApiPath, writeEnv } from "./_setup.js";
@@ -183,13 +183,16 @@ function bootstrapArgs(manifest, pm, name, promptArgs = {}) {
 * files are written with `force`, silently replacing the framework defaults.
 */
 async function applyManifestWiring(dir, templateDir, manifest, opts) {
-	const { alias, kizloPath } = manifest.config;
+	const { kizloPath } = manifest.config;
+	const hasSrcDir = fs.existsSync(path.join(dir, "src"));
+	const alias = aliasWithSlash(effectiveAlias(dir, kizloPath, manifest.config.alias));
 	const scaffold = buildScaffoldContext(dir, {
 		dirRel: kizloPath,
-		hasSrcDir: fs.existsSync(path.join(dir, "src")),
+		hasSrcDir,
 		alias,
 		clientUrl: void 0
 	});
+	if (manifest.config.alias && !alias) p.log.warn(`The ${manifest.name ?? manifest.id} scaffold declares no tsconfig path for \`${aliasWithSlash(manifest.config.alias)}\`, so Kizlo wrote relative imports instead.`);
 	recordDependencies(dir, manifest);
 	const changes = changesFor(manifest, "create", { includeExamples: opts.includeExamples });
 	const files = [{

package/dist/cli/commands/dev.js

@@ -1,4 +1,4 @@
-import { createStack, dockerHint, dockerStatus } from "../wp/docker.js";
+import { createStack, dockerHint, dockerStatus, stackStatus } from "../wp/docker.js";
 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";
@@ -117,8 +117,8 @@ function updateWpEnv(cfg, info) {
 * The full fresh-install write goes through {@link updateWpEnv} instead; this covers the resume path it
 * skips. Returns true when it changed the file. The app still needs a restart to read the new value.
 */
-function syncLocalUrl(cfg, url) {
-	const envPath = join(cfg.configDir, ".env");
+function syncLocalUrl(configDir, url) {
+	const envPath = join(configDir, ".env");
 	if (!existsSync(envPath)) return false;
 	const existing = readFileSync(envPath, "utf8");
 	if (readEnvValue(existing, "KIZLO_LOCAL_WP_URL") === url) return false;
@@ -134,23 +134,23 @@ function syncLocalUrl(cfg, url) {
 * `next dev` child server — nothing stops them automatically when we die. A dying process
 * also can't be trusted to finish async work (a closed terminal breaks its stdout
 * mid-write), so this process does no docker work on the way out. It only needs to
-* *exit*; the watchdog, watching our PID from its own session, stops it the moment
-* we're gone — by Ctrl+C, SIGTERM, a closed tab, SIGKILL, or a crash alike.
+* *exit*; the watchdog verifies our process identity from its own session and stops it
+* the moment we're gone, by Ctrl+C, SIGTERM, a closed tab, SIGKILL, or a crash alike.
 *
 * We trigger that exit two ways, because neither alone is enough: signal handlers (for
 * Ctrl+C / `kill`), and an stdin/TTY-close watch (for a closed terminal, whose SIGHUP
 * an `npm`/`pnpm` wrapper silently swallows — leaving us orphaned but alive otherwise).
 */
-function armForegroundTeardown(cfg) {
-	registerSession(cfg.project);
-	spawnWatchdog(cfg.project);
+async function armForegroundTeardown(cfg) {
+	const owner = await registerSession(cfg.project);
+	spawnWatchdog(cfg.project, owner);
 	let exiting = false;
-	const shutdown = (reason) => {
+	const shutdown = (line) => {
 		if (exiting) return;
 		exiting = true;
 		unregisterSession(cfg.project);
 		try {
-			note(`Stopping local WordPress (${reason})…`);
+			if (line) note(line);
 		} catch {}
 		process.exit(0);
 	};
@@ -158,15 +158,20 @@ function armForegroundTeardown(cfg) {
 		"SIGINT",
 		"SIGTERM",
 		"SIGHUP"
-	]) process.on(signal, () => shutdown(signal));
+	]) process.on(signal, () => shutdown(stopping(signal)));
 	if (process.stdin.isTTY) {
 		process.stdin.resume();
 		for (const event of [
 			"end",
 			"close",
 			"error"
-		]) process.stdin.on(event, () => shutdown("terminal closed"));
+		]) process.stdin.on(event, () => shutdown(stopping("terminal closed")));
 	}
+	return shutdown;
+}
+/** The teardown line for a session leaving while its stack is still up, which this one is stopping. */
+function stopping(reason) {
+	return `Stopping local WordPress (${reason})…`;
 }
 /**
 * Bring the dev stack's containers up for `cfg`: clear any stale containers, resolve the published
@@ -218,7 +223,7 @@ 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, creds.url)) note("Updated .env WordPress URL to the current network address — restart your app to pick it up");
+	} 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);
 	const { green, dim, bold, reset } = palette();
 	const ms = Date.now() - start;
@@ -259,17 +264,21 @@ async function rebootStack(cwd, label) {
 * teardown first (so a mid-startup cancel still stops partial containers), boots and prints the
 * summary, then parks. While parked it watches `.env` and `kizlo.config.*`: a change reboots the whole
 * stack in place so a new port, connection, or fixture takes effect without rerunning the command. The
-* reboot runs in the same process — the watchdog and session keep watching this PID throughout — and is
-* guarded so the credential/URL writes it makes to `.env` don't trigger another reboot. A referenced
+* reboot runs in the same process. The watchdog and session keep watching this owner throughout, and it
+* is guarded so the credential/URL writes it makes to `.env` don't trigger another reboot. A referenced
 * timer holds the event loop open — an unresolved promise alone would not, so without it Node would
 * empty its loop and exit straight after printing.
 */
 async function startForeground(cfg) {
 	const cwd = process.cwd();
 	let ready = await prepareStack(cfg);
-	armForegroundTeardown(ready);
+	const shutdown = await armForegroundTeardown(ready);
 	await bootAndReport(ready);
-	let stopContract = await startWatcher(ready.configDir);
+	const stack = {
+		status: () => stackStatus(ready.project),
+		onStopped: () => shutdown()
+	};
+	let stopContract = await startWatcher(ready.configDir, { stack });
 	let reloading = false;
 	const reload = async (changed) => {
 		if (reloading) return;
@@ -277,7 +286,7 @@ async function startForeground(cfg) {
 		try {
 			stopContract?.();
 			ready = await rebootStack(cwd, `${changed} changed — restarting the session`);
-			stopContract = await startWatcher(ready.configDir);
+			stopContract = await startWatcher(ready.configDir, { stack });
 		} catch (error) {
 			log.error("Failed to reload the dev session:", error);
 		} finally {

package/dist/cli/commands/generate.js

@@ -1,30 +1,73 @@
 import { log } from "../daemon/logger.js";
-import { resolveConfig } from "../daemon/config.js";
-import { generateOnce } from "../daemon/generate.js";
+import { resolveConfig, resolveWordPressClientDir } from "../daemon/config.js";
+import { PartialContractError, generateOnce, generateWorkspaceClientOnce, reportGenerationError } from "../daemon/generate.js";
+import { testWordPressCredentials } from "./_test-wordpress.js";
+import path from "node:path";
 import { defineCommand } from "citty";
 
 //#region src/cli/commands/generate.ts
+/**
+* Report and exit non-zero. A refused partial contract says one thing here that it cannot say
+* anywhere else, since its diagnostics are already on screen and the useful detail is what strict
+* mode did not do to the files on disk.
+*/
+function fail(message, error) {
+	if (error instanceof PartialContractError) log.error(`${error.message} The generated client on disk is unchanged.`);
+	else reportGenerationError(message, error);
+	process.exit(1);
+}
 const generate = defineCommand({
 	meta: {
 		name: "generate",
 		description: "Generate the Kizlo contract once (for builds and CI)"
 	},
-	args: { dir: {
-		type: "string",
-		description: "Override the Kizlo directory (defaults to kizlo.config.ts)"
-	} },
+	args: {
+		dir: {
+			type: "string",
+			description: "Override the Kizlo directory (defaults to kizlo.config.ts)"
+		},
+		strict: {
+			type: "boolean",
+			description: "Fail instead of generating a client WordPress had to exclude routes or types from"
+		},
+		test: {
+			type: "boolean",
+			description: "Generate against WordPress left running by kizlo test"
+		}
+	},
 	async run({ args }) {
-		const cfg = await resolveConfig(process.cwd(), { dir: args.dir });
+		const cwd = process.cwd();
+		const strict = args.strict === true;
+		let credentials;
+		if (args.test) try {
+			credentials = await testWordPressCredentials(cwd);
+		} catch (error) {
+			log.error(error instanceof Error ? error.message : String(error));
+			process.exitCode = 1;
+			return;
+		}
+		const options = {
+			credentials,
+			strict
+		};
+		const wordpressClientDir = await resolveWordPressClientDir(cwd);
+		if (wordpressClientDir) try {
+			const result = await generateWorkspaceClientOnce(cwd, wordpressClientDir, options);
+			const file = path.resolve(cwd, wordpressClientDir, "wordpress.ts");
+			log.success(`WordPress client ${result === "generated" ? "written to" : "already current at"} ${file}`);
+		} catch (error) {
+			fail("Failed to generate the WordPress client:", error);
+		}
+		const cfg = await resolveConfig(cwd, { dir: args.dir });
 		if (!cfg) {
-			log.info("No Kizlo server directory configured, nothing to generate. Set `dir` in kizlo.config.ts or pass --dir.");
+			if (!wordpressClientDir) log.info("No Kizlo server directory configured, nothing to generate. Set `dir` in kizlo.config.ts or pass --dir.");
 			return;
 		}
 		let ok;
 		try {
-			ok = await generateOnce(cfg);
+			ok = await generateOnce(cfg, options);
 		} catch (error) {
-			log.error("Failed to generate the Kizlo contract:", error);
-			process.exit(1);
+			fail("Failed to generate the Kizlo contract:", error);
 		}
 		if (!ok) {
 			log.error(`No Kizlo server found in ${cfg.serverEntry}`);

package/dist/cli/commands/init.js

@@ -1,4 +1,4 @@
-import { addDependencyArgs, aliasWithSlash, detectImportAlias, detectInvokingPackageManager, detectPackageManager, ensureGitignored, getVersion, loadEnvFiles, persistPackageManagerField, readPersistedAlias, runCommandAsync } from "../utils.js";
+import { addDependencyArgs, aliasWithSlash, detectImportAlias, detectInvokingPackageManager, detectPackageManager, effectiveAlias, ensureGitignored, getVersion, loadEnvFiles, persistPackageManagerField, readPersistedAlias, runCommandAsync } from "../utils.js";
 import { DEFAULT_REGISTRY, detectTemplates, fetchRegistry, isSingleTemplate, listTemplates, resolveRegistry } from "../presets/source.js";
 import { adaptFile, changesFor, fileEntries, isOlderVersion, minCliError, patchEntries, readManifest, renderNote, resolveDependencies, unmetRequirement } from "../presets/template.js";
 import { collectConnectionFromEnv, collectConnectionInteractively, dirPath, envConflicts, nextStepsNote, orCancel, provisionLocalWordPress, readEnvExample, resolveEnvKeys, selectPackageManager, syncRemote, validate, withApiPath, writeEnv } from "./_setup.js";
@@ -254,13 +254,15 @@ const init = defineCommand({
 				...aliasCtx,
 				envKeys
 			}) : await collectInteractively(aliasCtx);
-			setup.alias = aliasWithSlash(setup.alias);
+			const dirRel = setup.dir.replace(/^\.\//, "").replace(/\/+$/, "");
+			const requestedAlias = aliasWithSlash(setup.alias);
+			setup.alias = aliasWithSlash(effectiveAlias(cwd, dirRel, setup.alias));
+			const droppedAlias = requestedAlias && !setup.alias ? requestedAlias : void 0;
 			if (apiPath && setup.baseUrl) setup.baseUrl = withApiPath(setup.baseUrl, apiPath);
 			const includeExamples = yes ? true : orCancel(await p.confirm({
 				message: "Add example pages?",
 				initialValue: true
 			}));
-			const dirRel = setup.dir.replace(/^\.\//, "").replace(/\/+$/, "");
 			const serverDirRel = path.join(dirRel, "server");
 			const clientUrl = setup.siteUrl && !sameOrigin(setup.siteUrl, setup.baseUrl) ? setup.baseUrl : void 0;
 			const scaffold = buildScaffoldContext(cwd, {
@@ -306,6 +308,7 @@ const init = defineCommand({
 			}
 			if (shouldPersistPm) persistPackageManagerField(cwd, pm);
 			const warnings = [];
+			if (droppedAlias) warnings.push(`No tsconfig path maps \`${droppedAlias}\` onto ${dirRel}, so relative imports were written instead. Add \`"${droppedAlias}*": ["./${hasSrcDir ? "src/" : ""}*"]\` to your tsconfig \`paths\` and re-run to use the alias.`);
 			const scaffolded = [];
 			let gitignore = "present";
 			const kizloSpec = `kizlo@${manifest.dependencies?.kizlo ?? `^${getVersion()}`}`;

package/dist/cli/commands/test.js

@@ -3,6 +3,7 @@ import { isSeeded, recordedPort } from "../wp/utils.js";
 import { log } from "../daemon/logger.js";
 import { isFree } from "../wp/ports.js";
 import { groupDefault, pickStackPort, withSpinner } from "../utils.js";
+import { warnVersionDrift } from "../wp/version.js";
 import { resolveTestConfig } from "../daemon/config.js";
 import { testStack } from "../wp/stack.js";
 import { runPluginPhpunit } from "../wp/phpunit.js";
@@ -37,7 +38,7 @@ async function resolveTestPort(cfg, stack, fresh) {
 	if (!fresh) {
 		const live = await stack.publishedPort();
 		if (live !== void 0) return live;
-		const recorded = recordedPort();
+		const recorded = recordedPort(cfg.project);
 		if (recorded !== void 0) {
 			if (await isFree(recorded)) return recorded;
 			log.error(`The test WordPress port ${recorded} (from a previous run) is now held by something else.\nFree that port, or run \`kizlo test reset\` to rebuild on a fresh one.`);
@@ -60,9 +61,16 @@ async function bringUp(cfg, stack, fresh = false) {
 		port
 	}));
 	await withSpinner("Starting test WordPress", () => bound.composeUp(), "Test WordPress ready");
+	await warnVersionDrift({
+		wpCli: bound.wpCli,
+		tag: cfg.wordpressTag,
+		resetCommand: "kizlo test reset",
+		warn: (message) => log.warn(message)
+	});
 	if (await isSeeded()) log.info("Test WordPress already seeded — skipping seed.");
 	else await withSpinner("Seeding WordPress", () => runSeeds({
 		port,
+		project: cfg.project,
 		fixtures: cfg.fixtures
 	}), "WordPress seeded");
 	return {