kizlo 0.18.0 → 0.20.0

package/dist/cli/daemon/generate.js

@@ -1,6 +1,5 @@
 import { generateContract } from "../../shared/contract.js";
 import { integrationEnv, resolveWordPressConnection } from "../../kizlo.js";
-import { WORDPRESS_CLIENT_META_REL } from "../wp/constants.js";
 import { node } from "../../integrations/node/integration.js";
 import { log } from "./logger.js";
 import { loadEnvFiles } from "../utils.js";
@@ -15,16 +14,16 @@ import fs from "node:fs";
 
 //#region src/cli/daemon/generate.ts
 /**
-* The generated barrel is 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.
+* The generated barrel is also written as a stub by `kizlo init`. It re-exports `introspection`
+* rather than pre-wrapping it: a server entry passes `createKizlo({ introspection })` itself, so the
+* rest of the options stay visible at the call site instead of hiding inside a generated object.
 */
 const CONTRACT_BARREL = [
 	`import type { procedures } from ".."`,
 	`import contractJson from "./contract.json"`,
 	``,
 	`export const contract = contractJson as unknown as typeof procedures`,
-	`export { endpoints, type WordPressClient } from "./wordpress"`,
+	`export { introspection, type WordPressClient } from "./introspection"`,
 	``
 ].join("\n");
 var LegacyRouterExportError = class extends Error {
@@ -34,22 +33,22 @@ var LegacyRouterExportError = class extends Error {
 	}
 };
 /**
-* `wordpress.ts` before the first generation. WordPress is reachable but untyped until then, so a
+* `introspection.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
+* connected. `kizlo dev` / `kizlo generate` replaces this with the real introspection. `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 = [
+const INTROSPECTION_STUB = [
 	`import type { WP_Client } from "kizlo"`,
 	``,
-	`export const endpoints = {} as any`,
+	`export const introspection = {} as any`,
 	``,
-	`export type WordPressClient = WP_Client<typeof endpoints>`,
+	`export type WordPressClient = WP_Client<typeof introspection>`,
 	``,
 	`declare module "kizlo" {`,
 	`\tinterface WordPressClientRegistry {`,
-	`\t\tendpoints: typeof endpoints`,
+	`\t\tintrospection: typeof introspection`,
 	`\t}`,
 	`\tinterface WordPressEndpointRegistry {`,
 	`\t\t[path: string]: any`,
@@ -123,8 +122,8 @@ function formatDiagnostic(diagnostic) {
 * 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.
+* it does not own. Strict generation makes the opposite trade for CI, where an introspection silently
+* short of routes typechecks clean and ships the gap.
 */
 var PartialContractError = class extends Error {
 	excluded;
@@ -155,7 +154,7 @@ function reportDiagnostics(document, strict) {
 	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.`);
+	log.warn(`Generating without the ${excluded.size} excluded ${excluded.size === 1 ? "contribution" : "contributions"} above. Their routes and types are missing from the introspection; \`kizlo generate --strict\` refuses the contract instead.`);
 }
 /**
 * Plugin versions already named as outdated. `kizlo dev` refetches every few seconds, and the answer
@@ -178,7 +177,7 @@ function reportPluginVersion(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, integrationEnv([node()])).credentials, {
+	const result = await fetchIntrospection(options.credentials ?? resolveWordPressConnection(integrationEnv([node()])).credentials, {
 		etag: options.strict ? void 0 : etag,
 		fetch: options.fetch
 	});
@@ -189,74 +188,69 @@ async function fetchDocument(cwd, options, etag) {
 	return result;
 }
 /**
-* Produce the WordPress client without writing it or its ETag cache. Health checks use this to ask
+* Produce the introspection source 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 = {}) {
+async function generateIntrospectionSource(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.
+* Write `introspection.ts` at its resolved path, revalidating against the ETag cache. The one place
+* the introspection reaches disk, whether or not the project has a server: a server-backed app writes
+* it under `generated/`, and a package that only ships procedures writes it at its own `dir.introspection`.
 */
-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);
+async function generateIntrospectionOnce(cfg, options = {}) {
+	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);
 	if (!result?.document) return "unchanged";
 	const generated = generateWordPressModule(result.document);
 	await assertGeneratedClientCompiles(generated);
-	const contents = generated.source;
+	fs.mkdirSync(path.dirname(file), { recursive: true });
 	fs.mkdirSync(path.dirname(metaPath), { recursive: true });
+	atomicWrite(file, generated.source);
 	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.
+* Generate everything `dir` resolves: the introspection always, plus the contract and barrel when a
+* server is present. The server is loaded before the introspection is fetched, so a legacy `router`
+* export is named as a migration error even with WordPress unreachable; a server whose entry exports no
+* `procedures` still gets its introspection, and reports `contract: "empty"`.
 */
 async function generateOnce(cfg, options = {}) {
 	loadEnvFiles(cfg.cwd);
-	const entry = path.resolve(cfg.cwd, cfg.serverEntry);
-	const server = await importIgnoringVirtualModules(cfg.cwd, entry);
-	if (!server.procedures) {
-		if (server.router) throw new LegacyRouterExportError(cfg.serverEntry);
-		return false;
+	let procedures;
+	if (cfg.server) {
+		const entry = path.resolve(cfg.cwd, cfg.server.entry);
+		const server = await importIgnoringVirtualModules(cfg.cwd, entry);
+		if (!server.procedures && server.router) throw new LegacyRouterExportError(cfg.server.entry);
+		procedures = server.procedures;
 	}
-	const contract = JSON.stringify(await generateContract(server.procedures));
-	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;
+	const introspection = await generateIntrospectionOnce(cfg, options);
+	if (!cfg.server) return {
+		introspection,
+		contract: "none"
+	};
+	if (!procedures) return {
+		introspection,
+		contract: "empty"
+	};
+	const contract = JSON.stringify(await generateContract(procedures));
+	fs.mkdirSync(path.resolve(cfg.cwd, cfg.server.contractDir), { recursive: true });
+	atomicWrite(path.resolve(cfg.cwd, cfg.server.contractPath), contract);
+	atomicWrite(path.resolve(cfg.cwd, cfg.server.barrelPath), CONTRACT_BARREL);
+	if (introspection === "generated") log.success("WordPress introspection generated");
+	return {
+		introspection,
+		contract: "built"
+	};
 }
 
 //#endregion
-export { CONTRACT_BARREL, PartialContractError, WORDPRESS_STUB, generateOnce, generateWordPressOnce, generateWordPressSource, generateWorkspaceClientOnce, reportGenerationError };
+export { CONTRACT_BARREL, INTROSPECTION_STUB, PartialContractError, generateIntrospectionOnce, generateIntrospectionSource, generateOnce, reportGenerationError };

package/dist/cli/daemon/watch.js

@@ -2,9 +2,9 @@ import { integrationEnv, resolveWordPressConnection } from "../../kizlo.js";
 import { node } from "../../integrations/node/integration.js";
 import { log } from "./logger.js";
 import { loadEnvFiles } from "../utils.js";
-import { resolveConfig, resolveWordPressClientDir } from "./config.js";
+import { resolveConfig } from "./config.js";
 import { IntrospectionFetchError } from "../../wordpress/fetch-introspection.js";
-import { generateOnce, generateWordPressOnce, generateWorkspaceClientOnce, reportGenerationError } from "./generate.js";
+import { generateIntrospectionOnce, generateOnce, reportGenerationError } from "./generate.js";
 import { acquire, lockPath, release } from "./lock.js";
 import path from "node:path";
 import { FSWatcher } from "chokidar";
@@ -19,51 +19,49 @@ function debounce(fn, delay) {
 }
 async function regenerate(cfg, credentials) {
 	try {
-		if (await generateOnce(cfg, { credentials })) log.success("Contract updated");
-		else log.warn(`No Kizlo server found in ${cfg.serverEntry}`);
+		const result = await generateOnce(cfg, { credentials });
+		if (result.contract === "built") log.success("Contract updated");
+		else if (result.contract === "empty" && cfg.server) log.warn(`No Kizlo server found in ${cfg.server.entry}`);
 	} catch (error) {
 		reportGenerationError("Failed to update the Kizlo contract:", error);
 	}
 }
-/** Watches the server directory and regenerates the contract on change. */
-async function watch(cfg, credentials) {
+/** Watches the server directory and regenerates the contract on change. Only called when a server is present. */
+async function watch(cfg, server, credentials) {
 	const watcher = new FSWatcher({
 		persistent: true,
 		ignoreInitial: true,
-		ignored: path.resolve(cfg.cwd, cfg.generatedDir)
+		ignored: path.resolve(cfg.cwd, server.contractDir)
 	});
 	const onChange = debounce(() => regenerate(cfg, credentials), 300);
-	watcher.add(path.resolve(cfg.cwd, cfg.serverDir));
+	watcher.add(path.resolve(cfg.cwd, server.dir));
 	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.
+* Report the introspection poll's pass. It 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.
 */
-function reportGeneration(subject, stack) {
+function reportGeneration(stack) {
 	let reported;
 	return async (run) => {
 		try {
-			if (await run() === "generated") log.success(`WordPress ${subject} updated`);
+			if (await run() === "generated") log.success("WordPress introspection updated");
 			stack?.answered();
 			if (reported !== void 0) {
 				reported = void 0;
-				log.success(`Updating the WordPress ${subject} again`);
+				log.success("Updating the WordPress introspection 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);
+			reportGenerationError("Failed to update the WordPress introspection:", error);
 		}
 	};
 }
@@ -96,26 +94,20 @@ function endOnStoppedStack(stack, now = Date.now) {
 	};
 }
 /**
-* 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.
+* One pass of the introspection poll: refetch and rewrite `introspection.ts` when WordPress has changed.
+* A server-backed app and a package that ships only procedures both take this same pass, since each has
+* exactly one introspection to keep current; the plugin's PHP changing is picked up either way. The
+* contract is not refreshed here; the file watcher rebuilds it on a server source change.
 */
-function createWordPressRefresh(cwd, cfg, wordpressClientDir, options, stack) {
-	const guard = stack ? endOnStoppedStack(stack) : void 0;
-	const service = reportGeneration("service", guard);
-	const client = reportGeneration("client", guard);
+function createWordPressRefresh(cfg, options, stack) {
+	const introspection = reportGeneration(stack ? endOnStoppedStack(stack) : void 0);
 	return async () => {
-		if (cfg) await service(() => generateWordPressOnce(cfg, options));
-		if (wordpressClientDir) await client(() => generateWorkspaceClientOnce(cwd, wordpressClientDir, options));
+		await introspection(() => generateIntrospectionOnce(cfg, 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);
+function refreshWordPress(cfg, credentials, stack) {
+	const refresh = createWordPressRefresh(cfg, { credentials }, stack);
 	let refreshing = false;
 	const timer = setInterval(() => {
 		if (refreshing) return;
@@ -128,12 +120,11 @@ function refreshWordPress(cwd, cfg, wordpressClientDir, credentials, stack) {
 	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
-* script, or a second `kizlo dev`), or when no server `dir` is configured, in which case
-* the caller carries on without watching. Used by `kizlo dev`, both when it boots a local
-* stack and when it runs the watcher alone, so a single terminal covers the whole dev loop.
+* Acquire the single-instance lock, generate 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 script, or a second `kizlo dev`), or when nothing is configured to
+* generate, in which case the caller carries on without watching. Used by `kizlo dev`, both when it
+* boots a local stack and when it runs the watcher alone, so a single terminal covers the whole dev loop.
 */
 async function startWatcher(cwd, opts) {
 	const lock = lockPath(cwd);
@@ -144,26 +135,22 @@ async function startWatcher(cwd, opts) {
 	let handedOver = false;
 	try {
 		const cfg = await resolveConfig(cwd, { dir: opts?.dir });
-		const wordpressClientDir = await resolveWordPressClientDir(cwd);
-		if (!cfg && !wordpressClientDir) {
+		if (!cfg) {
 			log.info("skipping the contract generation.");
 			return;
 		}
 		loadEnvFiles(cwd);
-		const { credentials } = resolveWordPressConnection(void 0, integrationEnv([node()]));
-		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}`);
+		const { credentials } = resolveWordPressConnection(integrationEnv([node()]));
+		try {
+			const result = await generateOnce(cfg, { credentials });
+			if (result.contract === "built") log.success("Contract generated");
+			else if (result.contract === "empty" && cfg.server) log.warn(`No Kizlo server found in ${cfg.server.entry}`);
+			else if (result.introspection === "generated") log.success("WordPress introspection generated");
 		} 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);
+		const watcher = cfg.server ? await watch(cfg, cfg.server, credentials) : void 0;
+		const wordpressRefresh = refreshWordPress(cfg, credentials, opts?.stack);
 		let stopped = false;
 		handedOver = true;
 		return () => {

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

@@ -34,9 +34,7 @@ declare const CREDENTIALS_REL = ".kizlo/test.json";
  * working dir rather than next to the generated files on purpose: it describes one machine's last
  * fetch, so a fresh clone has to regenerate rather than trust a cache it never populated.
  */
-declare const WORDPRESS_META_REL = ".kizlo/wordpress.meta.json";
-/** Same, for the standalone client written by `wordpressClientDir`. Separate so the two never share one ETag. */
-declare const WORDPRESS_CLIENT_META_REL = ".kizlo/wordpress.client.meta.json";
+declare const INTROSPECTION_META_REL = ".kizlo/introspection.meta.json";
 /**
  * Fixed folder the local WordPress install lives in, relative to the config root. The whole install
  * (core, themes, uploads, plugins) is bind-mounted here; `kizlo dev reset` wipes it. It sits under
@@ -56,4 +54,4 @@ declare const DEFAULT_PLUGINS: PluginSource[];
 declare const TEST_ADMIN: Omit<TestAdminUser, "id" | "applicationPassword">;
 declare const TEST_USER: Omit<TestUser, "id">;
 //#endregion
-export { COMPOSE_FILE, CONFIG_FILES, CREDENTIALS_REL, DEFAULT_PLUGINS, DEFAULT_PORT, DEFAULT_WORDPRESS_TAG, LOCAL_DIR_REL, OPCACHE_INI, REMAP_ENTRYPOINT, SEED_MARKER_OPTION, SEED_VERSION, TEST_ADMIN, TEST_USER, WORDPRESS_CLIENT_META_REL, WORDPRESS_META_REL, githubRelease, kizloRelease };
+export { COMPOSE_FILE, CONFIG_FILES, CREDENTIALS_REL, DEFAULT_PLUGINS, DEFAULT_PORT, DEFAULT_WORDPRESS_TAG, INTROSPECTION_META_REL, LOCAL_DIR_REL, OPCACHE_INI, REMAP_ENTRYPOINT, SEED_MARKER_OPTION, SEED_VERSION, TEST_ADMIN, TEST_USER, githubRelease, kizloRelease };

package/dist/cli/wp/constants.js

@@ -44,9 +44,7 @@ const CREDENTIALS_REL = ".kizlo/test.json";
 * working dir rather than next to the generated files on purpose: it describes one machine's last
 * fetch, so a fresh clone has to regenerate rather than trust a cache it never populated.
 */
-const WORDPRESS_META_REL = ".kizlo/wordpress.meta.json";
-/** Same, for the standalone client written by `wordpressClientDir`. Separate so the two never share one ETag. */
-const WORDPRESS_CLIENT_META_REL = ".kizlo/wordpress.client.meta.json";
+const INTROSPECTION_META_REL = ".kizlo/introspection.meta.json";
 /**
 * Fixed folder the local WordPress install lives in, relative to the config root. The whole install
 * (core, themes, uploads, plugins) is bind-mounted here; `kizlo dev reset` wipes it. It sits under
@@ -83,4 +81,4 @@ const TEST_USER = {
 };
 
 //#endregion
-export { COMPOSE_FILE, CONFIG_FILES, CREDENTIALS_REL, DEFAULT_PLUGINS, DEFAULT_PORT, DEFAULT_WORDPRESS_TAG, LOCAL_DIR_REL, OPCACHE_INI, REMAP_ENTRYPOINT, SEED_MARKER_OPTION, SEED_VERSION, TEST_ADMIN, TEST_USER, WORDPRESS_CLIENT_META_REL, WORDPRESS_META_REL, githubRelease, kizloRelease };
+export { COMPOSE_FILE, CONFIG_FILES, CREDENTIALS_REL, DEFAULT_PLUGINS, DEFAULT_PORT, DEFAULT_WORDPRESS_TAG, INTROSPECTION_META_REL, LOCAL_DIR_REL, OPCACHE_INI, REMAP_ENTRYPOINT, SEED_MARKER_OPTION, SEED_VERSION, TEST_ADMIN, TEST_USER, githubRelease, kizloRelease };

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

@@ -53,13 +53,16 @@ interface SeedContext {
 /**
  * A plugin to ensure installed + active during bootstrap. A bare string is a
  * wp.org slug (the installed name and the install source are the same). The
- * object form is for any other source — a zip URL or a local path — where the
- * installed slug (`name`, used for activation checks) can't be derived from the
- * source. `source` is passed straight to `wp plugin install`.
+ * object form names an install source explicitly, either a wp.org slug or a zip
+ * URL, when the installed slug (`name`, used for activation checks) cannot be
+ * derived from the source or the wp.org release must be pinned. `version` is
+ * passed to `wp plugin install --version` when present. `source` is passed
+ * straight to `wp plugin install`.
  */
 type PluginSource = string | {
   name: string;
   source: string;
+  version?: string;
 };
 /**
  * A local plugin directory to bind-mount into the dev stack (`kizlo dev`) instead

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

@@ -14,15 +14,15 @@ import { DevPluginSource, Fixture, PluginSource, SettleContext, TestCredentials
  * Bumping `SEED_VERSION` invalidates older marks and forces a reseed.
  */
 declare function isSeeded(): Promise<boolean>;
-/** Resolve a `PluginSource` to the `(name, source)` pair `ensurePlugin` needs. */
-declare function resolvePluginSource(plugin: PluginSource): [name: string, source: string];
+/** Resolve a `PluginSource` to the arguments `ensurePlugin` needs. */
+declare function resolvePluginSource(plugin: PluginSource): [name: string, source: string, version?: string];
 /**
  * Ensure a plugin is active without ever re-downloading. Plugin files persist in
  * the `wp_data` volume, so an already-installed plugin is just activated; the
  * download (`source` = release zip URL or wp.org slug) happens only when the files
  * are absent (i.e. after `wp reset` wipes the volume).
  */
-declare function ensurePlugin(name: string, source: string): Promise<void>;
+declare function ensurePlugin(name: string, source: string, version?: string): Promise<void>;
 /**
  * Activate a bind-mounted local plugin by its directory basename (the slug the
  * mount lands at under `wp-content/plugins`). Idempotent: the files arrive via the

package/dist/cli/wp/utils.js

@@ -29,9 +29,14 @@ async function isSeeded() {
 	]);
 	return marker.code === 0 && marker.stdout.trim() === SEED_VERSION;
 }
-/** Resolve a `PluginSource` to the `(name, source)` pair `ensurePlugin` needs. */
+/** Resolve a `PluginSource` to the arguments `ensurePlugin` needs. */
 function resolvePluginSource(plugin) {
-	return typeof plugin === "string" ? [plugin, plugin] : [plugin.name, plugin.source];
+	if (typeof plugin === "string") return [plugin, plugin];
+	return plugin.version === void 0 ? [plugin.name, plugin.source] : [
+		plugin.name,
+		plugin.source,
+		plugin.version
+	];
 }
 /**
 * Ensure a plugin is active without ever re-downloading. Plugin files persist in
@@ -39,7 +44,7 @@ function resolvePluginSource(plugin) {
 * download (`source` = release zip URL or wp.org slug) happens only when the files
 * are absent (i.e. after `wp reset` wipes the volume).
 */
-async function ensurePlugin(name, source) {
+async function ensurePlugin(name, source, version) {
 	if ((await compose([
 		"exec",
 		"-T",
@@ -69,6 +74,7 @@ async function ensurePlugin(name, source) {
 		"plugin",
 		"install",
 		source,
+		...version === void 0 ? [] : [`--version=${version}`],
 		"--activate"
 	]);
 }

package/dist/comment/errors.js

@@ -22,7 +22,6 @@ const LIST_COMMENT_ERROR_MAP = defineErrorMap({
 	}
 });
 const SUBMIT_COMMENT_ERROR_MAP = defineErrorMap({
-	COMMENT_USER_NOT_FOUND: {},
 	COMMENT_ID_NOT_FOUND: {},
 	COMMENT_CLOSED: {},
 	COMMENT_LOGIN_REQUIRED: {},

package/dist/comment/index.js

@@ -98,26 +98,26 @@ const COMMENT_PROCEDURES = {
 		const connInfo = await context.getConnInfo();
 		if (!connInfo?.ip) throw new Error("Connection IP is required.");
 		if (!connInfo?.userAgent) throw new Error("Connection user agent is required.");
-		const user = await context.getAuthUser();
-		if (!user) {
+		const session = await context.getSession();
+		if (!session) {
 			if (!input.body.captchaToken) throw errors.COMMENT_CAPTCHA_REQUIRED();
 			if (!await context.verifyCaptcha(input.body.captchaToken)) throw errors.COMMENT_CAPTCHA_INVALID();
 		}
-		const response = await context.wordpress.kizlo.comments.create({
-			user_id: user?.id,
+		const submission = {
 			author_ip: connInfo.ip,
 			user_agent: connInfo.userAgent,
 			content: input.body.content,
 			post_id: input.body.postId,
+			user_email: session?.email,
 			author_email: input.body.authorEmail,
 			author_name: input.body.authorName,
 			author_url: input.body.authorUrl,
 			parent: input.body.parentId
-		});
+		};
+		const response = await context.wordpress.kizlo.comments.create(submission);
 		if (response.error) switch (response.error.code) {
 			case "require_name_email": throw errors.COMMENT_NAME_EMAIL_REQUIRED();
 			case "require_valid_email": throw errors.COMMENT_INVALID_EMAIL();
-			case "kizlo_invalid_user": throw errors.COMMENT_USER_NOT_FOUND();
 			case "require_valid_comment": throw errors.COMMENT_EMPTY_CONTENT();
 			case "not_logged_in": throw errors.COMMENT_LOGIN_REQUIRED();
 			case "comment_closed": throw errors.COMMENT_CLOSED();